Compare Origin Commits via the API

Compare two revisions with GET https://api.cursor.com/v1/origin/repos/{ownerSlug}/{repoName}/compare/{basehead}. Official reference: Origin API → Compare Commits (OpenAPI OriginService_CompareCommits).

Origin is in Early Beta and subject to change. Authenticate with an installation access token (oit_…) or a user access token that carries repository:contents:read. Availability: Early Beta per the API overview.

Path basehead is {base}...{head} (three dots). Either side may be a SHA, branch, tag, or symbolic ref such as HEAD. Refs that contain / must use their SHA. Unrelated histories return NOT_FOUND.

The response is a CommitComparison summary: status (identical | ahead | behind | diverged), aheadBy, behindBy, plus baseCommit, headCommit, and mergeBaseCommit in the list projection (no nested stats or files). Per Current limitations, commit comparison returns summary data rather than an embedded commit list. Page file diffs with List Comparison Files.

Cost: 1 point against the principal budget (ordinary read).

Path parameters

Param	Required	Meaning
ownerSlug	yes	Owning entity's unique slug
repoName	yes	Repo name, unique to the owner
basehead	yes	{base}...{head}; refs with / must use SHA

curl --request GET \
  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/compare/main...feature' \
  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Branch name with a slash — resolve to SHAs first:

curl --request GET \
  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/compare/3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8...9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4' \
  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response

Example shape from the OpenAPI (CommitComparison):

{
  "status": "ahead",
  "aheadBy": 2,
  "behindBy": 0,
  "baseCommit": {
    "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",
    "commit": {
      "author": {
        "name": "Jane Doe",
        "email": "jane@acme.dev",
        "date": "2026-08-01T09:30:00Z"
      },
      "committer": {
        "name": "Jane Doe",
        "email": "jane@acme.dev",
        "date": "2026-08-01T09:30:00Z"
      },
      "message": "Add launch telemetry",
      "tree": {
        "sha": "a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8"
      }
    },
    "parents": [
      {
        "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"
      }
    ]
  },
  "headCommit": {
    "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",
    "commit": {
      "author": {
        "name": "Jane Doe",
        "email": "jane@acme.dev",
        "date": "2026-08-01T09:30:00Z"
      },
      "committer": {
        "name": "Jane Doe",
        "email": "jane@acme.dev",
        "date": "2026-08-01T09:30:00Z"
      },
      "message": "Add launch telemetry",
      "tree": {
        "sha": "a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8"
      }
    },
    "parents": [
      {
        "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"
      }
    ]
  },
  "mergeBaseCommit": {
    "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",
    "commit": {
      "author": {
        "name": "Jane Doe",
        "email": "jane@acme.dev",
        "date": "2026-08-01T09:30:00Z"
      },
      "committer": {
        "name": "Jane Doe",
        "email": "jane@acme.dev",
        "date": "2026-08-01T09:30:00Z"
      },
      "message": "Add launch telemetry",
      "tree": {
        "sha": "a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8"
      }
    },
    "parents": [
      {
        "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"
      }
    ]
  }
}

aheadBy counts commits head is ahead of the merge base; behindBy counts commits head is behind base. Fetch changed files with List Comparison Files on the same basehead.

Base URL: https://api.cursor.com/v1/origin.