List Origin Comparison Files via the API

Page files changed by a comparison with GET https://api.cursor.com/v1/origin/repos/{ownerSlug}/{repoName}/compare/{basehead}/files. Official reference: Origin API → List Comparison Files (OpenAPI OriginService_ListComparisonFiles).

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.

The diff is head against the merge base of base and head. Path basehead is {base}...{head}; refs containing / must use their SHA. Unrelated histories return NOT_FOUND.

Default pageSize is 30; values above 100 clamp to 100. A pageToken is bound to the resolved comparison, page size, and file cursor — keep basehead and pageSize matching the token on follow-ups. If the comparison's resolved commits change since the token was issued, the request fails with INVALID_ARGUMENT; restart from the first page.

Cost: 5 points against the principal budget (heavy read: List Comparison Files is on the official rate-limit heavy-read list).

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

Query parameters

Param	Required	Meaning
pageSize	no	Max changed files (default 30, max 100)
pageToken	no	Opaque cursor from a previous nextPageToken

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

Response

The body carries files and an optional nextPageToken (empty when no next page). Each file includes filename, status, additions, deletions, changes, and patch.

Example shape from the OpenAPI:

{
  "files": [
    {
      "filename": "src/telemetry.ts",
      "status": "modified",
      "additions": 6,
      "deletions": 3,
      "changes": 9,
      "patch": "@@ -12,6 +12,9 @@\n import { ignite } from \"./ignition\";\n+import { emitLaunchTelemetry } from \"./telemetry\";\n"
    }
  ]
}

Treat page tokens as opaque. Restart pagination when basehead or pageSize changes, or when resolved commits drift. Get the summary (status, aheadBy, behindBy) with Compare Commits on the same basehead.

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