METAGROK
API / list-origin-branches-via-api

API

List Origin Branches via the API

list-origin-branches-via-api

Page a repository's branches and tip commits with GET https://api.cursor.com/v1/origin/repos/{ownerSlug}/{repoName}/branches. Official reference: Origin API (OpenAPI OriginService_ListBranches).

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.

Branches return in ascending name order. Cost: 1 point against the principal budget (ordinary read).

Create a branch ref with Create Origin Git Ref via the API. List commits on a branch with List Origin Commits via the API.

Path parameters

Param Required Meaning
ownerSlug yes Owning entity's unique slug
repoName yes Repo name, unique to the owner

Query parameters

Param Required Meaning
pageSize no Max branches to return (default 30 when unset or 0; values above 100 clamp to 100)
pageToken no Opaque cursor from a previous nextPageToken; empty for the first page. The token encodes the page offset, so pageSize on a follow-up request is ignored when a token is supplied. 
curl --request GET \
  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/branches?pageSize=30' \
  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response

200 returns branches and an optional nextPageToken (empty when there is no next page). Each branch has:

Field Meaning
name Branch name without the refs/heads/ prefix (for example main)
commit.sha Full hex SHA at the tip of the branch

Example shape from the OpenAPI:

{
  "branches": [
    {
      "name": "main",
      "commit": {
        "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4"
      }
    }
  ],
  "nextPageToken": ""
}

Errors

Status When
400 Bad request
401 Missing or invalid token
403 Token lacks repository:contents:read
404 Repo not found or not visible (not-found and no-access are indistinguishable)
429 Rate limited

Pitfalls

  • Branch names omit the refs/heads/ prefix. Pass main, not refs/heads/main, when you reuse the name on other endpoints.
  • After the first page, keep sending the same pageToken chain; changing pageSize mid-walk is ignored once a token is present.
  • An empty repository still returns 200 with an empty branches array when the caller can see the repo.

Related