Diff Endpoints

REST API endpoints for retrieving differences between branches in Infrahub

Diff endpoints allow you to compare branches and identify changes to files, artifacts, and data. These are essential for change management and code review workflows.

Get Diff Files

Retrieve file differences from Git repositories between branches or time periods.

GET /api/diff/files

Query Parameters

branch · string

Name of the branch to compare. Defaults to the main branch.

time_from · string

Start time for the diff in absolute or relative format (e.g., “2024-01-01T00:00:00Z” or “-1d”)

time_to · string

End time for the diff in absolute or relative format (e.g., “2024-01-02T00:00:00Z” or “now”)

branch_only · boolean · default: "true"

If true, only show changes specific to this branch. If false, show all changes.

Response

Returns a nested object structure organized by branch name and repository ID.

[branch_name] · object

Object containing repositories with file changes for the branch

[repository_id] · object

Repository information and file changes

id · string

Repository unique identifier

display_name · string

Human-readable repository name

commit_from · string

Starting commit hash

commit_to · string

Ending commit hash

branch · string

Branch name

files · array

Array of file changes

location · string

File path within the repository

action · string

Type of change (added, modified, deleted)

Example

curl -X GET "https://infrahub.example.com/api/diff/files?branch=feature-branch&branch_only=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response

{
  "feature-branch": {
    "repo-abc-123": {
      "id": "repo-abc-123",
      "display_name": "Network Configurations",
      "commit_from": "a1b2c3d4e5f6",
      "commit_to": "f6e5d4c3b2a1",
      "branch": "feature-branch",
      "files": [
        {
          "location": "configs/router01.cfg",
          "action": "modified"
        },
        {
          "location": "configs/router02.cfg",
          "action": "added"
        }
      ]
    }
  }
}

Get Diff Artifacts

Retrieve artifact differences between the current branch and the default branch.

GET /api/diff/artifacts

Query Parameters

branch · string

Name of the branch to compare against the default branch

Response

Returns an object mapping artifact IDs to their diff information.

[artifact_id] · object

Artifact difference information

id · string

Artifact unique identifier

branch · string

Branch name where the change occurred

display_label · string

Human-readable artifact name

action · string

Type of change: “added”, “updated”, “removed”, or “unchanged”

target · object

Target information for the artifact

id · string

Target node ID

kind · string

Target node kind

display_label · string

Target display name

Example

curl -X GET "https://infrahub.example.com/api/diff/artifacts?branch=feature-branch" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response

{
  "artifact-123": {
    "id": "artifact-123",
    "branch": "feature-branch",
    "display_label": "Router Configuration",
    "action": "updated",
    "target": {
      "id": "device-456",
      "kind": "CoreDevice",
      "display_label": "router01.example.com"
    }
  },
  "artifact-124": {
    "id": "artifact-124",
    "branch": "feature-branch",
    "display_label": "Switch Configuration",
    "action": "added",
    "target": {
      "id": "device-457",
      "kind": "CoreDevice",
      "display_label": "switch01.example.com"
    }
  }
}

Compare Time Ranges

# Get all file changes in the last 24 hours
curl -X GET "https://infrahub.example.com/api/diff/files?time_from=-1d&time_to=now" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get changes between specific dates
curl -X GET "https://infrahub.example.com/api/diff/files?time_from=2024-01-01T00:00:00Z&time_to=2024-01-07T23:59:59Z" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Branch Comparison Workflow

# 1. Get file differences for a feature branch
FILE_DIFF=$(curl -X GET "https://infrahub.example.com/api/diff/files?branch=feature-branch" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -s)

echo "File changes:"
echo $FILE_DIFF | jq .

# 2. Get artifact differences for the same branch
ARTIFACT_DIFF=$(curl -X GET "https://infrahub.example.com/api/diff/artifacts?branch=feature-branch" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -s)

echo "Artifact changes:"
echo $ARTIFACT_DIFF | jq .

# 3. Count changes by action type
echo "Artifact change summary:"
echo $ARTIFACT_DIFF | jq '[.[] | .action] | group_by(.) | map({action: .[0], count: length})'

Authentication

All diff endpoints require authentication using either:

• Bearer Token: Include Authorization: Bearer YOUR_ACCESS_TOKEN header
• API Key: Include X-API-KEY: YOUR_API_KEY header

Use Cases

• Change Review: Review all changes before merging a branch
• Impact Analysis: Understand which artifacts will be affected by schema or data changes
• Audit Trail: Track what changed and when in Git repositories
• CI/CD Integration: Automate checks based on file or artifact changes

Diff Actions

The action field in responses indicates the type of change:

• added - New artifact or file created
• updated / modified - Existing artifact or file changed
• removed / deleted - Artifact or file deleted
• unchanged - No changes detected