Skip to main content
Compares a feature branch to its base so you can review every change before merging. 
GET /api/v1/repos/branches/diff?branch=BRANCH_NAME&base=BASE_BRANCH&ephemeral=true&ephemeral_base=false&path=src/main.go&path=README.md
Authorization: Bearer YOUR_JWT_TOKEN

​
Parameters

​
branch
string
required
The branch name to get the diff for
​
base
string
Base branch to compare against (defaults to repository’s default branch)
​
ephemeral
string
When true, resolves the branch ref under refs/namespaces/ephemeral/refs/heads/<branch>
​
ephemeral_base
string
When true, resolves the base ref under refs/namespaces/ephemeral/refs/heads/<base>
​
path
string
File path(s) to filter the diff. Can be specified multiple times to include multiple files. When provided, only returns diffs for the specified files and bypasses size/type filtering

​
JWT Requirements

  • The JWT must include the repository in the repo claim
  • Requires git:read scope

​
Response

{
  "branch": "feature/new-feature",
  "base": "main",
  "stats": {
    "files": 5,
    "additions": 120,
    "deletions": 30,
    "changes": 150
  },
  "files": [
    {
      "path": "src/feature.go",
      "state": "A",
      "old_path": "",
      "bytes": 2048,
      "is_eof": true,
      "raw": "diff --git a/src/feature.go b/src/feature.go\nnew file mode 100644\nindex 0000000..abc123\n--- /dev/null\n+++ b/src/feature.go\n@@ -0,0 +1,50 @@\n+package main\n+\n+func NewFeature() {\n+    // Implementation\n+}\n"
    },
    {
      "path": "src/main.go",
      "state": "M",
      "old_path": "",
      "bytes": 1024,
      "is_eof": true,
      "raw": "diff --git a/src/main.go b/src/main.go\nindex abc123..def456 100644\n--- a/src/main.go\n+++ b/src/main.go\n@@ -10,6 +10,8 @@\n+    feature := NewFeature()\n+    feature.Run()\n"
    }
  ],
  "filtered_files": [
    {
      "path": "go.sum",
      "state": "M",
      "old_path": "",
      "bytes": 50000,
      "is_eof": true
    }
  ]
}

​
Notes

  • Shows all changes in the branch compared to the base branch
  • If base is not specified, compares against the repository’s default branch (usually “main”)
  • Uses three-dot diff notation internally (base…branch) to show changes since branch diverged
  • Large files and binary files are included in filtered_files without diff content
  • When path is specified, size and type filtering is bypassed—requested files are always returned with full diff content
  • Git status codes in state: A (added), M (modified), D (deleted), R (renamed), C (copied), T (type changed)
  • For renamed files, path is the new location and old_path is the previous location
  • In SDK responses, renamed files are normalized to state: "renamed" and keep the original git status in rawState (for example R054)
  • Useful for reviewing all changes in a feature branch before merging
  • For more about ephemeral branches, see the Ephemeral branches guide

​
Error Responses

​
404 Not Found
string
Branch or base branch doesn’t exist
​
401 Unauthorized
string
Invalid JWT or missing git:read scope
​
400 Bad Request
string
Missing branch parameter or invalid ephemeral/ephemeral_base value