List Origin Matching Git Refs via the API

List Git references whose names start with a prefix using either GET https://api.cursor.com/v1/origin/repos/{ownerSlug}/{repoName}/git/matching-refs (optional ref query) or GET https://api.cursor.com/v1/origin/repos/{ownerSlug}/{repoName}/git/matching-refs/{ref} (prefix in the path). Official reference: Origin API (OpenAPI OriginService_ListMatchingGitRefs_2 and OriginService_ListMatchingGitRefs).

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.

Both URL shapes share the same handler. A trailing slash on ref is preserved (heads/ → refs/heads/). A leading refs/ is accepted and normalized. The symbolic HEAD is matched exactly (it does not sit under refs/). Empty ref on the query form lists all refs. Empty repositories return 409 Conflict.

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
ref	path form only	Prefix to match; typically heads/<prefix> or tags/<prefix>

Query parameters (query form)

Param	Required	Meaning
ref	no	Same prefix rules as the path form; empty lists all refs

# Query form — list all refs (omit ref) or filter with ?ref=
curl --request GET \
  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/git/matching-refs?ref=heads/' \
  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

# Path form — prefix in the path segment
curl --request GET \
  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/git/matching-refs/heads/feature' \
  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response

200 returns a ListMatchingGitRefsResponse: refs is an array of matching GitRef objects sorted by full ref name. Each item has ref (full name, e.g. refs/heads/main) and object with sha and type (commit, tree, blob, or tag). For annotated tags, object.type is tag and object.sha is the tag object SHA (unpeeled).

{
  "refs": [
    {
      "ref": "refs/heads/main",
      "object": {
        "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",
        "type": "commit"
      }
    }
  ]
}

For a single exact name, use Get Git Ref. Base URL: https://api.cursor.com/v1/origin.