Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us