Origin API

Origin is in Early Beta and subject to change. Review the OpenAPI specification when updating an integration.

Origin is Cursor's code forge. Its public REST API lets apps and tools work with Origin repositories, commits, checks, pull requests, and app installations.

Origin Apps authenticate with app JWTs and installation access tokens. See Authentication.
View the full OpenAPI specification for detailed schemas and examples.
Agents can load the llms.txt index or the complete reference as Markdown at llms-full.txt.

Overview

Origin apps implement an OAuth-style installation consent and GitHub App–style authentication model:

The app signs a short-lived EdDSA JWT with its Ed25519 private key.
The app exchanges that JWT and an installation ID for a short-lived installation access token (oit_…).
The installation token calls repository APIs and authenticates Git over HTTPS within the installation's approved repositories and scopes.
Origin sends signed webhook deliveries to the app's registered webhook URL.

Base URL

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

Endpoint paths in the reference include the full /v1/origin prefix.

Requests and responses use application/json. JSON field names are camelCase. Timestamps are RFC 3339 strings. Protobuf 64-bit integers, including pull request numbers and version numbers, are encoded as JSON strings.

Getting started

Origin access

Browse Origin at cursor.com/codebase.
Manage app settings at cursor.com/codebase/settings/apps.
Generate an app signing key and register only the public key.

Origin CLI

Install the Origin CLI and sign in:

curl -fsSL https://downloads.cursor.com/origin/install.sh | shorigin auth login

Clone an existing repository:

origin repo clone '{ownerSlug}/{repoName}'# or use git directlygit clone 'https://origin.cursor.com/{ownerSlug}/{repoName}.git'

Apps clone using Git HTTPS authentication with an installation access token, not a user login.

Installation

Send a customer workspace admin to:

https://cursor.com/codebase/apps/install  ?client_id=APP_ID  &scope=SPACE_SEPARATED_SCOPES  &redirect_uri=REGISTERED_CALLBACK  &state=RANDOM_ANTI_FORGERY_VALUE  &summary=SHORT_REASON_FOR_ACCESS  &include_granted_scopes=true

Parameter	Required	Description
`client_id`	Yes	Origin App ID.
`scope`	Yes	Space-separated scopes. `repository:metadata:read` is added automatically.
`redirect_uri`	Yes for partner-initiated installs	Exact registered callback URI.
`state`	Strongly recommended	Random anti-forgery value echoed as the `state` claim of the installation receipt. Generate it before redirecting and verify the claim on callback.
`summary`	No	Short explanation displayed during consent.
`include_granted_scopes`	No	When `true`, retain existing grants and request only additions.

The workspace admin chooses the target owner, approved scopes, and either all repositories or selected repositories. The customer, not the app, controls repository access.

After approval, Origin redirects to the registered callback:

https://ci.example.com/origin/callback?installation_receipt=RECEIPT_JWT

Verify the installation receipt, then store the installation ID from its sub claim. You need it whenever you mint an installation access token.

Installations use one of two repository-selection modes:

all: the installation can access every repository owned by the selected target.
selected: the installation can access only repositories selected by the workspace admin.

Both modes cover mirrored repositories as well as native Origin ones, so a mirror appears in GET /installation/repos and can be selected. A mirror is read-only until it becomes a stable outbound mirror: see Mirrored repositories.

Use GET /installation/repos with an installation token to discover the repositories available to that installation. App JWT endpoints can list, inspect, and delete the app's installations. Deleting an installation prevents new tokens from being minted.

Installation receipt

installation_receipt is a short-lived compact JWT signed by Origin. It proves the installation approval came from Origin rather than a forged redirect and carries everything the callback needs. Cursor refuses to redirect without one, so external callbacks always carry it.

JOSE header:

{  "alg": "EdDSA",  "kid": "origin-key-id",  "typ": "origin-installation-receipt+jwt"}

Claims:

{  "iss": "https://api.cursor.com/v1/origin",  "aud": "app_01...",  "sub": "i_01...",  "namespace_id": "ns_01...",  "iat": 1786465200,  "exp": 1786465500,  "jti": "RECEIPT_UUID",  "installedBy": {    "id": "user_01...",    "email": "installer@example.com"  },  "state": "ORIGINAL_VALUE"}

aud is your app ID and sub is the installation ID to use when minting installation access tokens.
namespace_id is the stable ID of the namespace the app was installed into.
installedBy identifies the user who performed this install or re-consent. It describes the current action, so on a re-consent it can differ from the durable installedBy on Get App Installation.
Receipts expire five minutes after issuance. jti is unique per receipt.
state is present only when the install URL carried a non-empty state, and echoes that value. Match it against the anti-forgery value you generated before redirecting.

Verify the receipt before trusting the callback: resolve the signing key from the JWKS by the kid header, require alg EdDSA and typ origin-installation-receipt+jwt, and validate the signature, iss, aud, and exp. Reject the callback when verification fails.

The receipt is not an installation access token. Never send it as a Bearer credential; mint installation tokens through Create Installation Access Token instead.

Authentication

Send REST credentials as Bearer tokens:

curl --request GET \  --url https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME \  --header "Authorization: Bearer $ORIGIN_TOKEN"

Generate an app signing key

Origin Apps authenticate with an Ed25519 key pair. Generate the pair locally, then register only the public key at cursor.com/codebase/settings/apps. An app can hold up to 10 active signing keys.

The private key must stay secret. Do not upload it, paste it into app settings, commit it to a repository, or share it. Store it in a secrets manager. Cursor stores only the public key.

Create a PKCS#8 private key and a PEM SPKI public key with OpenSSL:

openssl genpkey -algorithm ED25519 -out origin-app-private.pemopenssl pkey -in origin-app-private.pem -pubout -out origin-app-public.pem

The public key file starts with -----BEGIN PUBLIC KEY-----. Paste that PEM when you add a signing key. Use the matching private key only to sign app JWTs.

App JWT

Sign a short-lived JWT with the Ed25519 private key paired with one of the app's active signing keys. Generate that pair as described in Generate an app signing key.

JOSE header:

{  "alg": "EdDSA",  "kid": "app_01...",  "typ": "JWT"}

Claims:

{  "iss": "app_01...",  "aud": "origin-apps",  "iat": 1782928800,  "exp": 1782929100}

Set iss and kid to the app ID. Use a lifetime of approximately five minutes.

Authorization: Bearer APP_JWT

Use an app JWT for app-level operations such as reading app metadata, managing installations, minting installation tokens, and recovering webhook deliveries.

Installation access token

Call POST /app/installations/{installationId}/access_tokens with an app JWT. Installation tokens begin with oit_.

Authorization: Bearer oit_...

The response includes expiresAt. Mint tokens just in time, refresh them before expiration, treat them like passwords, and never log them.

Removing the installation, or deleting the app, invalidates its installation tokens before expiresAt. The REST API and Git over HTTPS then reject the token with 401. Do not retry with the same token; the app must be reinstalled before it can mint a working one.

An installation token cannot exceed the installation's approved scopes or repository access. You can attenuate a token to fewer scopes or repositoryIds. Empty or omitted arrays inherit the complete installation grant.

Use installation tokens for repository-scoped operations, including pull requests, check-run writes, and Git over HTTPS.

Git HTTPS authentication

Installation access tokens authenticate Git over HTTPS. The Git endpoint uses HTTP Basic authentication: the password is the installation token, and the username is x-access-token. Bearer credentials belong on the REST API; Git HTTPS rejects them.

Mint a token from Create Installation Access Token immediately before the Git operation. Tokens expire after at most 15 minutes.

Clone, fetch, and pull require repository:contents:read. Push requires repository:contents:write. The token must include the target repository in its grant.

Pushing also requires the repository's owner to be eligible to write to Origin, the same requirement Create Repo carries. A user owner must be on a Pro, Pro Student, Pro+, Ultra, or Start plan. A team owner must have an active paid team plan, must not be on Privacy Mode (Legacy), and must not have Origin turned off by a team admin. A push to a repository whose owner is ineligible returns 403. Clone, fetch, and pull do not carry this requirement.

Read cloneUrl from Get Repo or List App Installation Repositories. Both the GitHub-shaped path (https://origin.cursor.com/OWNER_SLUG/REPO_NAME.git) and the legacy /git/ path clone.

git clone "https://x-access-token:${INSTALLATION_TOKEN}@origin.cursor.com/OWNER_SLUG/REPO_NAME.git"

Embedding the token in the URL stores it in .git/config. After a successful clone, rewrite the remote so later commands do not reuse an expired secret:

git remote set-url origin "https://origin.cursor.com/OWNER_SLUG/REPO_NAME.git"

To keep the token out of the remote URL, supply it through Git's credential helper:

git -c credential.helper="!f() { echo username=x-access-token; echo password=${INSTALLATION_TOKEN}; }; f" \  clone "https://origin.cursor.com/OWNER_SLUG/REPO_NAME.git"

The Origin CLI credential helper is for user logins. App integrations pass the installation token as shown here. Treat the token like a password, never log it, and mint a fresh one before expiresAt when a job still needs Git access.

On a mirrored repository, an installation token clones, fetches, and pulls, and Origin rejects git push with 403 until the mirror becomes a stable outbound mirror. See Mirrored repositories.

User-authenticated CLI requests

After signing in with the Origin CLI, use origin api for user-authenticated requests. The CLI resolves the user's credential and sends it as a Bearer token. App integrations should use app JWTs and installation access tokens instead.

Discovery and signing keys

Origin publishes unauthenticated discovery metadata and its active signing keys. The same keys sign webhook deliveries and installation receipts.

Discovery metadata identifies the issuer and jwks_uri:

curl https://api.cursor.com/v1/origin/.well-known/openid-configuration

{  "issuer": "https://api.cursor.com/v1/origin",  "jwks_uri": "https://api.cursor.com/v1/origin/keys",  "response_types_supported": ["id_token"],  "subject_types_supported": ["public"],  "id_token_signing_alg_values_supported": ["EdDSA"]}

/keys returns active Ed25519 JWKs:

curl https://api.cursor.com/v1/origin/keys

{  "keys": [    {      "kty": "OKP",      "crv": "Ed25519",      "use": "sig",      "alg": "EdDSA",      "kid": "origin-key-id",      "x": "PUBLIC_KEY_MATERIAL"    }  ]}

Cache the JWKS. Webhook signatures do not carry a key ID, so verification should try each active Ed25519 key. Installation receipts carry the signing key's kid in their JOSE header, so receipt verification can resolve the key directly.

Scopes

Request only the minimum scopes your app needs. repository:metadata:read and app or installation metadata access are granted automatically and should not be added separately to installation URLs.

Scope	Allows
`repository:metadata:read`	Read repository metadata. Added automatically.
`repository:contents:read`	Read commits, branches, contents, and low-level Git objects. Clone, fetch, and pull over Git HTTPS. Sync a mirrored repository from its upstream source.
`repository:contents:write`	Push over Git HTTPS. Merge pull requests.
`repository:pull_requests:read`	Read pull requests, changed files, pull request commits, and assigned labels.
`repository:pull_requests:write`	Create and update pull requests. Assign and remove pull request labels.
`repository:pull_requests:reviews:read`	Read pull request comments and submitted reviews.
`repository:pull_requests:reviews:write`	Create and update comments; create, update, and dismiss reviews.
`repository:checks:read`	Read check suites, runs, and check run annotations.
`repository:checks:write`	Create and update check suites and runs. Append check run annotations.
`repository:labels:read`	Read the label definitions a repository owns.
`repository:labels:write`	Create, update, and delete repository label definitions.
`repository:rulesets:read`	Read repository rulesets.
`repository:rulesets:write`	Create, update, and delete repository rulesets.

The installation token can only narrow these grants. It cannot add a scope or repository the workspace admin did not approve.

Mirrored repositories

An installation uses every scope it holds on a native Origin repository and on a stable outbound mirror. On a repository in any other mirror state, only two scopes apply:

repository:metadata:read
repository:contents:read

Every other scope returns 403 on that repository, whatever the workspace admin approved. Over the REST API, repository and contents reads, commit comparison, and Sync Mirror keep working, and Origin rejects pull requests, reviews, comments, checks, rulesets, and every write. Over Git HTTPS, clone, fetch, pull, and LFS download keep working, and Origin rejects push and LFS upload.

The mirror object on a repository does not tell you whether writes are allowed. A mirror partway through a transition can report mirror.status as outbound and still be read-only, so treat the 403 as authoritative rather than branching on mirror.status.

Rate limits

The Origin API uses a shared per-principal point budget that resets on a rolling one-minute window. Each authenticated principal kind has its own budget:

Principal	Default budget
Installation access token	3,000 points/minute
App JWT	6,000 points/minute
User or team service-account API key	600 points/minute

Every endpoint charges a fixed cost against that budget before the handler runs. Authentication and authorization failures are not charged.

Cost	Operations
0	Get Rate Limit. Status only; does not consume points.
1	Most read endpoints, plus Create Installation Access Token
5	Ordinary writes, plus these heavier reads: Get Commit, List Commit Files, and List Pull Request Files
10	Create Repo and Merge Pull Request

Cursor can raise per-app minute budgets for design partners. Contact Cursor if your integration needs a higher limit.

Response headers

Charged responses and Get Rate Limit include:

Header	Description
`X-RateLimit-Limit`	Points available in the current window for this principal
`X-RateLimit-Remaining`	Points left in the current window
`X-RateLimit-Used`	Points consumed in the current window
`X-RateLimit-Reset`	Unix timestamp (UTC seconds) when the window resets
`X-RateLimit-Resource`	Always `core` for the shared public API budget

X-RateLimit-Reset advertises a full 60-second window from the response time. The counter's window starts at the first charged request in a burst, not on a calendar-minute boundary.

Exceeding the limit

When a request would exceed the budget, the API returns HTTP 429 with:

Retry-After: seconds to wait before retrying (60)
The same X-RateLimit-* headers, with X-RateLimit-Remaining set to 0

{  "code": 8,  "message": "Rate limit exceeded: 3000 points per minute for this installation. Retry after 60s.",  "details": []}

Wait for Retry-After, or until X-RateLimit-Reset, before retrying. Use backoff with jitter when concurrent callers share one installation token.

Checking remaining quota

Call Get Rate Limit to read the current budget without consuming points. The response body mirrors the X-RateLimit-* headers for the shared core resource.

Webhooks

Origin sends signed HTTP POST requests to the app's registered HTTPS webhook URL with content-type: application/json.

Delivery is at least once. Deduplicate retries with webhook-id, durably accept the request, return 2xx quickly, and process the event asynchronously.

Origin retries transport errors, 429, and 5xx responses up to six total attempts. Retry delays are 30 seconds, 1 minute, 2 minutes, 4 minutes, and 8 minutes. Other 4xx responses are terminal.

To confirm a receiver works before any real event reaches it, call Ping Webhook.

Origin delivers events for mirrored repositories, and installation event payloads list them in the selected repository arrays. Delivery does not widen what the installation can call: see Mirrored repositories.

Headers

Header	Description
`content-type`	`application/json`
`user-agent`	`Cursor-Origin-Webhook/1.0`
`webhook-id`	Stable delivery ID and idempotency key.
`webhook-timestamp`	Unix timestamp included in the signature.
`webhook-signature`	`v1ed,BASE64_SIGNATURE`
`webhook-event-type`	Event slug for routing.
`webhook-event-id`	Underlying Origin event ID mirrored from the signed body.
`webhook-app-id`	Target app ID.
`webhook-installation-id`	Target installation ID.

Routing headers are conveniences. After signature verification, the body is authoritative.

Signature verification

Use the raw request body before parsing it. Construct:

lowercaseHex(SHA-256("<webhook-id>.<webhook-timestamp>.<raw-request-body>"))

Verify the Ed25519 signature over the UTF-8 bytes of that hexadecimal digest against an active Origin JWKS key. Reject timestamps more than five minutes from the current time.

import {  createHash,  createPublicKey,  verify,  type JsonWebKeyInput,} from "node:crypto";export async function verifyOriginWebhook(  body: Buffer,  headers: Record<string, string | undefined>): Promise<boolean> {  const id = headers["webhook-id"];  const timestamp = Number(headers["webhook-timestamp"]);  const signature = headers["webhook-signature"]    ?.split(/\s+/)    .find((value) => value.startsWith("v1ed,"));  const now = Math.floor(Date.now() / 1000);  if (    !id ||    !signature ||    !Number.isInteger(timestamp) ||    Math.abs(now - timestamp) > 300  ) {    return false;  }  const digest = createHash("sha256")    .update(`${id}.${timestamp}.`)    .update(body)    .digest("hex");  // Cache this response in production.  const { keys } = await fetch(    "https://api.cursor.com/v1/origin/keys"  ).then((response) => response.json()) as {    keys: JsonWebKeyInput[];  };  return keys.some((jwk) => {    try {      return verify(        null,        Buffer.from(digest),        createPublicKey({ key: jwk, format: "jwk" }),        Buffer.from(signature.slice(5), "base64")      );    } catch {      return false;    }  });}

Delivery envelope

Each request wraps the event payload with delivery, app, and installation identity:

{  "deliveryId": "whd_01...",  "appId": "app_01...",  "installationId": "i_01...",  "event": {    "id": "evt_01...",    "type": "pull_request.comment.created",    "eventTime": "2026-07-01T10:03:00Z",    "payload": {}  }}

deliveryId is stable across retries. event.id identifies the underlying domain event.

Events

Event	Delivered when
`repository.pushed`	One or more refs change in a push.
`pull_request.created`	A pull request opens.
`pull_request.head_ref.pushed`	The pull request head advances.
`pull_request.base_ref.updated`	The base ref or resolved base commit changes.
`pull_request.metadata.updated`	The title or description changes.
`pull_request.closed`	A pull request closes without merging.
`pull_request.merged`	A pull request merges.
`pull_request.reopened`	A closed pull request reopens.
`pull_request.published`	A draft becomes open.
`pull_request.comment.created`	A visible pull request comment is created.
`pull_request.review.submitted`	A review is submitted with any verdict.
`pull_request.review.dismissed`	A submitted review is dismissed, explicitly or by being superseded.
`pull_request.reviewer.added`	A reviewer is requested.
`pull_request.reviewer.removed`	A reviewer is removed.
`pull_request.reviewer.rerequested`	A reviewer is requested again.
`repository.check_run.created`	A check run is created.
`repository.check_run.completed`	A check run completes.
`installation.created`	The app is installed.
`installation.updated`	Scopes or repository selection change.
`installation.suspended`	The installation is suspended.
`installation.unsuspended`	A suspended installation is restored.
`installation.deleted`	The app is uninstalled.

The five installation.* events go to the app itself rather than to a repository subscription. Origin always sends them, so they do not appear in the app's selectable event list. Every other event in this table is a repository-scoped subscription.

Payload families

Pull request lifecycle events contain a pullRequest snapshot and repository reference. Route on event.type; there is no separate action field. The snapshot omits the pull request's assigned labels; read them from Get Pull Request or List Pull Requests.
Comment events contain a pullRequest reference and the affected comment.
Review events contain a pullRequest reference and the affected review. Both pull_request.review.submitted and pull_request.review.dismissed use this shape; on a dismissal the review carries review.dismissal with the dismissing actor, timestamp, and message. A review superseded by a newer decision carries a server-generated message.
Reviewer events contain a pullRequest reference, a reviewer, how the request was created, an optional actor, and a timestamp. Exactly one of reviewer.user or reviewer.group is present: reviewer.user.id is the encoded user ID (user_…, the same format as the organization API), and reviewer.group.id is the group public ID (grp_…). There is no public HTTP API to add, remove, or rerequest reviewers.
Check events contain repository, checkSuite, checkRun, and actor.
Push events contain one repository snapshot and up to 100 refUpdates. refUpdatesCount is authoritative. Optional tip metadata is best effort and does not provide a complete commits array. Merging a pull request advances the base ref, and that update is delivered as a push event; because Origin itself performs the merge push, the event names no pusher.
Installation events contain the installation snapshot and app identity. The snapshot carries installedBy, the user who originally installed the app, on all five installation.* events. Selected repository arrays may be capped at 5,000; repositoriesCount is authoritative.

Recovery

Use an app JWT to query GET /app/webhook/deliveries. Filter by delivery status, event type, installation, time range, or page token. delivered=false returns every delivery the receiver has never acknowledged with 2xx. Deliveries stay listable for seven days, so recover within that window.

Use POST /app/webhook/deliveries:batchRedeliver to queue redelivery for up to 100 delivery IDs. The operation deduplicates IDs and reports the result for each delivery.

Common conventions

Pagination

Paginated endpoints accept:

pageSize: defaults to 30 and is capped at 100.
pageToken: opaque token returned by the preceding page. Do not inspect or construct it.

Responses use a resource-specific collection field and nextPageToken. It is empty when no next page exists. Public list responses do not include total counts. Page tokens are bound to their originating resource and filters. Restart pagination when filters change. Invalid or mismatched non-empty tokens return 400.

Errors

Errors use a Google RPC-style body:

{  "code": 5,  "message": "resource not found",  "details": []}

Common HTTP statuses are 400, 401, 403, 404, 429, 500, and 503. Some Git-database operations also return 409 for repository-state conflicts. See Rate limits for 429 headers and retry behavior.

Use the HTTP status and code to branch on errors. Treat message as developer-facing text.

Every error response carries the request ID twice: in an X-Request-ID response header, and as a google.rpc.RequestInfo entry in details. Origin echoes the x-request-id you sent, or generates one when you send none. The RequestInfo entry is present even when message is an opaque internal error, so quote the request ID when you contact Cursor about a failed call.

Unmatched paths under /v1/origin, and requests that use the wrong method on a known path, return this same body rather than a generic router error. The message names the method and path and never echoes the query string.

Repository paths

Repository-scoped paths take the owner slug and repository name as {ownerSlug}/{repoName}. Both segments resolve case-insensitively, so any casing addresses the repository. Responses return the stored name and slug rather than the casing you sent, and Git HTTPS URLs resolve the same way. Compare repository names case-insensitively, and read the canonical casing from Get Repo.

Every repository-scoped path also accepts the repository's stable ID in place of the pair: send _ as the owner slug and the ID as the repository name, as in GET /v1/origin/repos/_/REPO_ID. Read the ID from the id field on Get Repo. The sentinel _ cannot be claimed as an owner slug, so the two forms never collide. In a Connect or JSON request, set ownerSlug to _ and name to the ID.

The ID form survives a rename, which makes it the stable way to address a repository. It grants nothing on its own: after Origin resolves the ID to a repository, your app still needs the same scope on that repository. An ID your app cannot reach returns the same 404 body as an ID that does not exist, so a response never confirms that a repository exists. A malformed ID returns 400. Create Repo takes an owner slug alone and rejects _.

Resource references

Resource snapshots contain the resource's current fields. Container context uses compact references instead of duplicating complete resources:

RepositoryReference identifies a repository.
PullRequestReference identifies a pull request and nests its repository reference.
ThreadReference identifies the thread containing a pull request comment.
OriginActor identifies a public actor as one of user, app, or serviceAccount. Exactly one variant is present; read the identity from that variant.

Current limitations

Namespace-wide repository listing and repository creation are not part of the partner API. Discover repositories through the installation.
Commit comparison returns summary data rather than a paginated compare-file or compare-commit stream.
Pull request comments expose thread IDs, but there is no first-class thread or resolution API.
Reviewer add, remove, and rerequest operations are webhook-only.
Push webhooks do not include a complete commit list.
Pull request merge supports native Origin repositories. Mirrored repositories are rejected.
A mirrored repository is read-only for an installation until it becomes a stable outbound mirror. See Mirrored repositories.

Implementation checklist

Store the Ed25519 private key in a secrets manager and rotate keys deliberately. See Generate an app signing key.
Verify the installation receipt on install callbacks and read the installation ID and state from its claims.
Use short-lived app JWTs and mint installation tokens just in time.
Use installation tokens, not app JWTs, for repository-scoped APIs, check-run writes, and Git HTTPS.
Request the minimum scopes and repository access.
Treat page tokens as opaque and restart pagination when filters change.
Keep check key values stable and readable. Use a new immutable externalId for each retry and increasing externalUpdatedAt values for updates.
Verify webhook signatures against the raw request body before parsing.
Deduplicate deliveries with webhook-id and process asynchronously after returning 2xx.
Ignore unknown JSON fields for forward compatibility.
Honor Retry-After and X-RateLimit-* headers. Use Get Rate Limit to monitor remaining points without consuming them.

Endpoint reference

Download the OpenAPI specification for the complete component schemas.

Generated OpenAPI path bindings such as identifier.ownerSlug and identifier.name appear here as ownerSlug and repoName. The URL segments and request behavior are unchanged.

The JSON snippets show schema-shaped placeholder values. Response field descriptions reflect the OpenAPI schema and current platform contract.

Apps and installations

Get Rate Limit

GET/v1/origin/rate_limit

Returns the authenticated principal's current public API rate limit status.

Accessing this endpoint does not consume rate limit points. The response covers the shared per-minute point budget used by other public API endpoints for this principal. See Rate limits.

Response Fields

resources object

Rate limit resources for the authenticated principal.

resources.core object

Shared per-minute point budget for public API endpoints.

resources.core.limit integer

Maximum points available in the current window.

resources.core.remaining integer

Points remaining in the current window.

resources.core.reset integer

Unix timestamp (UTC seconds) when the current window resets.

resources.core.used integer

Points consumed in the current window.

rate object

Alias of resources.core. Prefer resources.core in new clients.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/rate_limit' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "resources": {    "core": {      "limit": 0,      "remaining": 0,      "reset": 0,      "used": 0    }  },  "rate": {    "limit": 0,    "remaining": 0,    "reset": 0,    "used": 0  }}

Get Authenticated App

GET/v1/origin/app

Returns metadata for the authenticated app.

Response Fields

id string

Origin app identifier used as the JWT issuer and key ID.

slug string

Unique app slug.

displayName string

Human-readable app display name.

webhookUrl string

Registered HTTPS URL that receives the app's webhook deliveries.

events array

Webhook event subscriptions configured for the app.

createdAt string

RFC 3339 timestamp for app creation.

updatedAt string

RFC 3339 timestamp for the latest app metadata update.

installationRedirectUris array

Registered installation callback URIs; non-local callbacks must match exactly and use HTTPS.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/app' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "id": "string",  "slug": "string",  "displayName": "string",  "webhookUrl": "string",  "events": [    "string"  ],  "createdAt": "2026-01-01T00:00:00Z",  "updatedAt": "2026-01-01T00:00:00Z",  "installationRedirectUris": [    "string"  ]}

List App Installations

GET/v1/origin/app/installations

Lists installations for the authenticated app.

Query Parameters

pageSize integer

Max installations to return. Defaults to 30 when unset or 0. Values above 100 are clamped to 100.

pageToken string

Opaque cursor from a previous response's next_page_token. Empty for the first page.

Response Fields

installations array

Page of installations owned by the authenticated app.

installations[].id string

Installation identifier that the app stores and uses to mint installation access tokens.

installations[].appId string

Identifier of the installed app.

installations[].target object

Owner selected by the customer for this installation.

installations[].target.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

installations[].target.id string

Origin owner identifier.

installations[].target.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

installations[].createdAt string

RFC 3339 installation creation timestamp.

installations[].updatedAt string

RFC 3339 timestamp for the latest installation update.

installations[].repoSelectionMode string

Repository grant mode; exactly all or selected.

installations[].scopes array

Scopes approved for the installation.

installations[].installedBy object

The user who originally installed the app, not the most recent re-consent actor. Output-only. Absent when that user record can no longer be read.

installations[].installedBy.id string

Public identifier for the user, prefixed user_.

installations[].installedBy.email string

Email address of the user.

nextPageToken string

Opaque cursor for the next page; empty when there are no more pages.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/app/installations' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "installations": [    {      "id": "string",      "appId": "string",      "target": {        "slug": "string",        "id": "string",        "type": "team"      },      "createdAt": "2026-01-01T00:00:00Z",      "updatedAt": "2026-01-01T00:00:00Z",      "repoSelectionMode": "all",      "scopes": [        "string"      ],      "installedBy": {        "id": "string",        "email": "string"      }    }  ],  "nextPageToken": "string"}

Get App Installation

GET/v1/origin/app/installations/{installationId}

Returns a single installation for the authenticated app.

repoSelectionMode is all or selected.

Path Parameters

installationId string Required

Installation identifier.

Response Fields

id string

Installation identifier that the app stores and uses to mint installation access tokens.

appId string

Identifier of the installed app.

target object

Owner selected by the customer for this installation.

target.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

target.id string

Origin owner identifier.

target.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

createdAt string

RFC 3339 installation creation timestamp.

updatedAt string

RFC 3339 timestamp for the latest installation update.

repoSelectionMode string

Repository grant mode; exactly all or selected.

scopes array

Scopes approved for the installation.

installedBy object

The user who originally installed the app, not the most recent re-consent actor. Output-only. Absent when that user record can no longer be read.

installedBy.id string

Public identifier for the user, prefixed user_.

installedBy.email string

Email address of the user.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/app/installations/INSTALLATION_ID' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "id": "string",  "appId": "string",  "target": {    "slug": "string",    "id": "string",    "type": "team"  },  "createdAt": "2026-01-01T00:00:00Z",  "updatedAt": "2026-01-01T00:00:00Z",  "repoSelectionMode": "all",  "scopes": [    "string"  ],  "installedBy": {    "id": "string",    "email": "string"  }}

Delete App Installation

DELETE/v1/origin/app/installations/{installationId}

Deletes an installation that belongs to the authenticated app and prevents new installation tokens from being minted. Already-issued short-lived tokens may remain valid until they expire (at most 15 minutes). The response body is empty.

Path Parameters

installationId string Required

The unique identifier of the installation to delete. Bound from the URL path; the installation must belong to the authenticated app.

Response Fields

Successful requests return no response body.

curl --request DELETE \  --url 'https://api.cursor.com/v1/origin/app/installations/INSTALLATION_ID' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response:

204 No Content

Create Installation Access Token

POST/v1/origin/app/installations/{installationId}/access_tokens

Creates an installation access token for the authenticated app.

Requires app signing-JWT authentication, like GetAuthenticatedApp. The token is scoped to the named installation, which must belong to the authenticated app. Callers may attenuate the token to a subset of the installation's accepted scopes and accessible repositories.

repositoryIds can name a mirrored repository. The resulting token carries the installation's scopes, and Origin still applies the mirror ceiling on each request: see Mirrored repositories.

Path Parameters

installationId string Required

The unique identifier of the installation to scope the token to. Bound from the URL path; the installation must belong to the authenticated app.

Request Body

scopes array

Scope strings to grant the token. Values must be unique and included in the installation's accepted scopes. Empty or omitted inherits the full scope grant.

repositoryIds array

Repository IDs to grant the token. Values must be unique, accessible to the installation, and contain at most 50 entries. Empty or omitted inherits all accessible repositories.

Response Fields

token string

Short-lived installation credential with the oit_ prefix.

expiresAt string

RFC 3339 expiration time; the token expires after at most 15 minutes and never outlives the app JWT used to mint it.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/app/installations/INSTALLATION_ID/access_tokens' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{}'

Response shape:

{  "token": "string",  "expiresAt": "2026-01-01T00:00:00Z"}

List App Installation Repositories

GET/v1/origin/installation/repos

Lists repositories accessible to the authenticated app installation.

Requires an installation access token (oit_) minted by CreateInstallationAccessToken.

Partners discover their repositories through this endpoint. List entries are sparse repository summaries; use Get Repo for full timestamps. Get Repo includes the output-only cloneUrl.

Results include mirrored repositories. A mirror is read-only until it becomes a stable outbound mirror: see Mirrored repositories.

Query Parameters

pageSize integer

Max repositories to return. Defaults to 30 when unset or 0. Values above 100 are clamped to 100.

pageToken string

Opaque cursor from a previous response's next_page_token. Empty for the first page.

Response Fields

repositories array

Sparse repository summaries; use get-repository for full timestamps.

repositories[].id string

Origin repository identifier.

repositories[].name string

Repository name within its owner.

repositories[].fullName string

Combined owner and repository name, such as acme/api.

repositories[].owner object

Owner reference for the repository.

repositories[].owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

repositories[].owner.id string

Origin owner identifier.

repositories[].owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

repositories[].defaultBranch string

Repository default branch name.

repositories[].mirror object

Mirror metadata. Absent for a native repository and before a mirror's initial sync is ready.

repositories[].mirror.source string

Mirror source. Allowed value: github.

repositories[].mirror.sourceId string

Opaque repository identifier assigned by the source.

repositories[].mirror.status string

Effective mirror direction during a transition, until cutover completes. Allowed values: inbound, outbound.

nextPageToken string

Opaque cursor for the next page; empty when there are no more pages.

repoSelectionMode string

Reports whether the installation grants all repositories or only selected repositories.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/installation/repos' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "repositories": [    {      "id": "string",      "name": "string",      "fullName": "string",      "owner": {        "slug": "string",        "id": "string",        "type": "team"      },      "defaultBranch": "string",      "mirror": {        "source": "github",        "sourceId": "string",        "status": "inbound"      }    }  ],  "nextPageToken": "string",  "repoSelectionMode": "all"}

List Webhook Deliveries

GET/v1/origin/app/webhook/deliveries

Lists webhook deliveries for the authenticated app, newest first.

A delivery is one event owed to one app; its id is the Standard Webhooks webhook-id header the receiver sees. delivered=false is the recovery predicate: it selects every delivery that has never received a 2xx, including deliveries whose retry ladder ran out during an outage.

Deliveries are listable for seven days after they are created, and only while your app has an active installation in the delivery's namespace. App-targeted lifecycle events such as installation.deleted stay visible after the uninstall they describe.

Query Parameters

delivered boolean

Compares against delivered_at. delivered=false is the recovery predicate: it is evaluated server-side, so it cannot miss a delivery whose retry ladder exhausted mid-outage the way a caller-supplied time window silently does.

eventType string

Exact event type, e.g. pull_request.created.

installationId string

Narrow to one installation (WebhookDelivery.installation.id).

createdAfter string

Bound the delivery's creation time. For browsing, not for recovery.

createdBefore string

pageSize integer

Defaults to 30 when unset or 0. Values above 100 are clamped to 100.

pageToken string

Opaque cursor from a previous response's next_page_token. Empty for the first page.

Response Fields

deliveries array

Webhook deliveries for the authenticated app, ordered newest first. Each delivery ID is the webhook-id seen by the receiver.

deliveries[].id string

Stable delivery identifier and Standard Webhooks webhook-id value; use it as the idempotency key.

deliveries[].event object

The event this delivery carries.

deliveries[].event.id string

Underlying Origin event identifier. It may also be present alongside the stable delivery ID but is not the idempotency key.

deliveries[].event.type string

Event slug carried by the delivery for routing.

deliveries[].installation object

The installation this delivery belongs to. id is the current active installation for the target owner; unset when none exists (possible only for app-targeted lifecycle events after an uninstall).

deliveries[].installation.id string

Installation identifier associated with a webhook delivery list item.

deliveries[].installation.target object

Owner targeted by the installation.

deliveries[].installation.target.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

deliveries[].installation.target.id string

Origin owner identifier.

deliveries[].installation.target.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

deliveries[].createdAt string

Delivery creation timestamp used by createdAfter and createdBefore browsing filters.

deliveries[].deliveredAt string

Absence corresponds to delivered=false: the receiver has never acknowledged this delivery with a 2xx response.

deliveries[].lastAttempt object

The most recent HTTP attempt, when one exists: its response status code, latency, transport error, trigger, and time.

deliveries[].lastAttempt.id string

Webhook delivery attempt identifier.

deliveries[].lastAttempt.deliveryId string

Stable delivery identifier associated with this attempt.

deliveries[].lastAttempt.trigger string

Reason this delivery attempt was sent. Allowed values: automatic, manual.

deliveries[].lastAttempt.responseStatusCode integer

Unset when the POST produced no HTTP response (transport error, timeout).

deliveries[].lastAttempt.latencyMs integer

Delivery attempt latency in milliseconds.

deliveries[].lastAttempt.errorMessage string

Transport error detail when there was no HTTP response; empty otherwise.

deliveries[].lastAttempt.attemptedAt string

RFC 3339 timestamp for this delivery attempt.

nextPageToken string

Opaque cursor for the next page; empty when there are no more pages.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/app/webhook/deliveries' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "deliveries": [    {      "id": "string",      "event": {        "id": "string",        "type": "string"      },      "installation": {        "id": "string",        "target": {          "slug": "string",          "id": "string",          "type": "team"        }      },      "createdAt": "2026-01-01T00:00:00Z",      "deliveredAt": "2026-01-01T00:00:00Z",      "lastAttempt": {        "id": "string",        "deliveryId": "string",        "trigger": "automatic",        "responseStatusCode": 0,        "latencyMs": 0,        "errorMessage": "string",        "attemptedAt": "2026-01-01T00:00:00Z"      }    }  ],  "nextPageToken": "string"}

Batch Redeliver Webhook Deliveries

POST/v1/origin/app/webhook/deliveries:batchRedeliver

Asks Origin to send deliveries again.

The request means "ensure a send is in flight for each of these", not "add another send". It returns one result per unique input rather than failing the batch on a bad entry, so a single expired ID cannot block the rest of a recovery page. A 202 means the sends are queued; delivery itself is asynchronous, so poll List Webhook Deliveries for outcomes.

Request Body

deliveryIds array Required

Deliveries to send again. At most 100 unique entries, matching the pageSize ceiling on List Webhook Deliveries. Duplicates are removed, keeping first-seen order. An empty list, or more than 100 unique entries, returns InvalidArgument (HTTP 400).

Response Fields

results array

Accepted asynchronous redelivery results, one per unique delivery ID, with queued, already_in_flight, or not_found outcomes.

results[].deliveryId string

Requested stable delivery ID corresponding to this batch result.

results[].outcome string

Redelivery disposition: queued when a send was created, already_in_flight when a send was already running, and not_found otherwise. already_in_flight is a success, not an error. not_found covers unknown IDs, IDs older than the seven-day retention window, and namespaces where your app is no longer installed.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/app/webhook/deliveries:batchRedeliver' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "deliveryIds": [    "DELIVERY_ID"  ]}'

Response shape:

{  "results": [    {      "deliveryId": "string",      "outcome": "queued"    }  ]}

Ping Webhook

POST/v1/origin/app/webhook/pings

Sends a test delivery to the authenticated app's webhook URL and reports what the receiver answered.

Use it to verify a receiver while you set an app up, instead of waiting for a real event. Requires app signing-JWT authentication, like Get Authenticated App.

The receiver sees the production shape: the same headers and v1ed signature, verifiable against the signing keys, with webhook-event-type set to ping and a payload naming the app. A ping belongs to no installation, so the webhook-installation-id header and the envelope's installationId are both absent.

Origin sends the ping once, synchronously, and reports the outcome in the response. There are no retries, and a ping is not a domain event: it never appears in List Webhook Deliveries and cannot be redelivered. A receiver that fails is reported in the response rather than as an error. An app with no webhook URL configured returns FailedPrecondition (HTTP 400).

Request Body

The request takes no fields. Send an empty JSON object.

Response Fields

deliveryId string

The test delivery's webhook-id, matching the header the receiver saw.

eventId string

Event ID inside the signed envelope, the same value as event.id.

delivered boolean

True when the receiver answered with a 2xx status before the delivery timeout. Always present.

responseStatusCode integer

HTTP status the receiver answered with, or 0 when no response arrived because the connection failed or timed out. Always present.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/app/webhook/pings' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{}'

Response shape:

{  "deliveryId": "string",  "eventId": "string",  "delivered": true,  "responseStatusCode": 200}

Repositories

cloneUrl is an output-only HTTPS clone URL. Get Repo includes cloneUrl.

Partners discover their repositories through List App Installation Repositories. Namespace-wide repository listing and creation are not part of the partner API.

List Repos

GET/v1/origin/repos/{ownerSlug}

Lists repos belonging to an owner entity.

Path Parameters

ownerSlug string Required

Parent owner entity slug.

Query Parameters

pageSize integer

Max repos to return. Defaults to 30 when unset or 0. Values above 100 are clamped to 100.

pageToken string

Opaque cursor from a previous response's next_page_token. Empty for the first page.

filter string

Optional case-insensitive substring filter.

Response Fields

repositories array

Repositories belonging to the requested owner.

repositories[].id string

Origin repository identifier.

repositories[].name string

Repository name within its owner.

repositories[].fullName string

Combined owner and repository name, such as acme/api.

repositories[].owner object

Owner reference for the repository.

repositories[].owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

repositories[].owner.id string

Origin owner identifier.

repositories[].owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

repositories[].defaultBranch string

Repository default branch name.

repositories[].createdAt string

RFC 3339 repository creation timestamp.

repositories[].updatedAt string

RFC 3339 repository update timestamp.

repositories[].pushedAt string

RFC 3339 timestamp of the most recent push shown by the full repository response.

repositories[].cloneUrl string

Output-only HTTPS clone URL; the get-repository response includes it.

repositories[].mirror object

Mirror metadata. Absent for a native repository and before a mirror's initial sync is ready.

repositories[].mirror.source string

Mirror source. Allowed value: github.

repositories[].mirror.sourceId string

Opaque repository identifier assigned by the source.

repositories[].mirror.status string

Effective mirror direction during a transition, until cutover completes. Allowed values: inbound, outbound.

nextPageToken string

Opaque cursor for the next page; empty when there are no more pages.

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

Response shape:

{  "repositories": [    {      "id": "string",      "name": "string",      "fullName": "string",      "owner": {        "slug": "string",        "id": "string",        "type": "team"      },      "defaultBranch": "string",      "createdAt": "2026-01-01T00:00:00Z",      "updatedAt": "2026-01-01T00:00:00Z",      "pushedAt": "2026-01-01T00:00:00Z",      "cloneUrl": "string",      "mirror": {        "source": "github",        "sourceId": "string",        "status": "inbound"      }    }  ],  "nextPageToken": "string"}

Get Repo

GET/v1/origin/repos/{ownerSlug}/{repoName}

Returns a single repo by its (owner_id, name) identifier.

cloneUrl is an output-only HTTPS clone URL. Get repository includes cloneUrl.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

Response Fields

id string

Origin repository identifier.

name string

Repository name within its owner.

fullName string

Combined owner and repository name, such as acme/api.

owner object

Owner reference for the repository.

owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

owner.id string

Origin owner identifier.

owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

defaultBranch string

Repository default branch name.

createdAt string

RFC 3339 repository creation timestamp.

updatedAt string

RFC 3339 repository update timestamp.

pushedAt string

RFC 3339 timestamp of the most recent push shown by the full repository response.

cloneUrl string

Output-only HTTPS clone URL; the get-repository response includes it.

mirror object

Mirror metadata. Absent for a native repository and before a mirror's initial sync is ready.

mirror.source string

Mirror source. Allowed value: github.

mirror.sourceId string

Opaque repository identifier assigned by the source.

mirror.status string

Effective mirror direction during a transition, until cutover completes. Allowed values: inbound, outbound.

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

Response shape:

{  "id": "string",  "name": "string",  "fullName": "string",  "owner": {    "slug": "string",    "id": "string",    "type": "team"  },  "defaultBranch": "string",  "createdAt": "2026-01-01T00:00:00Z",  "updatedAt": "2026-01-01T00:00:00Z",  "pushedAt": "2026-01-01T00:00:00Z",  "cloneUrl": "string",  "mirror": {    "source": "github",    "sourceId": "string",    "status": "inbound"  }}

Create Repo

POST/v1/origin/repos/{ownerSlug}

Creates a repo belonging to an owner.

The owner must be eligible to write to Origin when the request is made. A user owner must be on a Pro, Pro Student, Pro+, Ultra, or Start plan. A team owner must have an active paid team plan, must not be on Privacy Mode (Legacy), and must not have Origin turned off by a team admin. An ineligible owner returns FailedPrecondition (HTTP 400). Reading existing repositories does not carry this requirement.

Repository names are claimed case-insensitively. A name that differs only in case from a repository the owner already has is rejected, so widgets and Widgets cannot coexist in one namespace. The name you send is stored as you send it.

The first push to a new repo can retarget its default branch. When that push only creates branches and none of them is the repo's stored default branch, Origin sets the default branch to the created branch, or to main or master when the push creates several and one of those names is among them. The default branch is otherwise unchanged. Read the current value from Get Repo.

Path Parameters

ownerSlug string Required

Parent owner entity's slug.

Request Body

name string Required

The repo name, unique to its owner. Required on create.

defaultBranch string

Default branch name. Always set on responses. On create, omitting this field or leaving it empty defaults to "main".

Response Fields

id string

Origin repository identifier.

name string

Repository name within its owner.

fullName string

Combined owner and repository name, such as acme/api.

owner object

Owner reference for the repository.

owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

owner.id string

Origin owner identifier.

owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

defaultBranch string

Repository default branch name.

createdAt string

RFC 3339 repository creation timestamp.

updatedAt string

RFC 3339 repository update timestamp.

pushedAt string

RFC 3339 timestamp of the most recent push shown by the full repository response.

cloneUrl string

Output-only HTTPS clone URL; the get-repository response includes it.

mirror object

Mirror metadata. Absent for a native repository and before a mirror's initial sync is ready.

mirror.source string

Mirror source. Allowed value: github.

mirror.sourceId string

Opaque repository identifier assigned by the source.

mirror.status string

Effective mirror direction during a transition, until cutover completes. Allowed values: inbound, outbound.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "name": "NAME"}'

Response shape:

{  "id": "string",  "name": "string",  "fullName": "string",  "owner": {    "slug": "string",    "id": "string",    "type": "team"  },  "defaultBranch": "string",  "createdAt": "2026-01-01T00:00:00Z",  "updatedAt": "2026-01-01T00:00:00Z",  "pushedAt": "2026-01-01T00:00:00Z",  "cloneUrl": "string",  "mirror": {    "source": "github",    "sourceId": "string",    "status": "inbound"  }}

List Branches

GET/v1/origin/repos/{ownerSlug}/{repoName}/branches

Lists the repo's branches and tip commits in ascending name order, paginated with page_size and page_token.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

Query Parameters

pageSize integer

Max branches to return. Defaults to 30 when unset or 0. Values above 100 are clamped to 100.

pageToken string

Opaque cursor from a previous response's next_page_token. Empty for the first page. Encodes the page offset, so page_size on a follow-up request is ignored when a token is supplied.

Response Fields

branches array

Paginated branch records containing branch name and tip commit SHA.

branches[].name string

Branch name.

branches[].commit object

The commit at the tip of the branch.

branches[].commit.sha string

Full hex SHA of the commit at the tip of the branch.

nextPageToken string

Opaque cursor for the next page; empty when there are no more pages.

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

Response shape:

{  "branches": [    {      "name": "string",      "commit": {        "sha": "string"      }    }  ],  "nextPageToken": "string"}

Sync Mirror

POST/v1/origin/repos/{ownerSlug}/{repoName}:syncMirror

Synchronizes one ref of a mirrored repository from its upstream source. Returns HTTP 200 when the sync target is satisfied, or HTTP 202 when the sync is still pending. wait=false (the default) schedules the sync and usually returns 202; it returns 200 immediately when sha is already reachable from ref. wait=true blocks until satisfied or the wait budget (~2 minutes) expires; expiry still returns 202 and the sync continues in the background. Repositories that do not pull from an upstream source are rejected.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

Request Body

ref string Required

Full git ref name to fetch. Must start with refs/ and name a ref after that prefix, for example refs/heads/main or refs/tags/v1. Short names such as main are rejected with INVALID_ARGUMENT.

wait boolean

When true, block until synced or the wait budget expires. Defaults to false.

sha string

Optional full commit object ID: 40- or 64-character hex. Omit or leave empty to wait on the tip of ref. When set and reachable from ref, the call returns early without waiting for other mirror work to drain. Other values are rejected with INVALID_ARGUMENT.

Response Fields

synced boolean

True when the sync target is known to be satisfied, false while the sync is still pending. Always present, mirroring the HTTP status: 200 when true, 202 when false.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME:syncMirror' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "ref": "refs/heads/main",  "wait": true}'

Response shape:

{  "synced": true}

Checks

The first run upsert creates its suite automatically.
Required checks match the installing app plus the suite key, and optionally a run key. name is display-only and is not used for matching.
Keep key values stable across attempts and readable for users, since required-check configuration is keyed on them.
Reuse externalId to update an attempt; use a new externalId for a retry.
Use checkRun.output for human-readable results:
- title: short result headline, up to 255 characters.
- summary: primary Markdown summary, up to 65,535 UTF-8 bytes.
- text: extended Markdown details, up to 65,535 UTF-8 bytes.
Use detailsUrl for a link to the provider's external results page.

Post Check Run

POST/v1/origin/repos/{ownerSlug}/{repoName}/check-runs

Upserts a check suite + check run using an installation access token with repository:checks:write. The write is attributed to the app that owns the authenticated installation. A repeated call with the same (repo, head_sha, suite.key, check.key) updates the existing check run in place rather than creating a duplicate.

The endpoint atomically resolves or creates the suite attempt and upserts one run attempt. externalUpdatedAt orders updates to the same run identity; stale retries cannot overwrite newer state.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

Request Body

headSha string Required

Head commit SHA the check run is reported against (40- or 64-char hex).

checkSuite object Required

The suite the check run belongs to; upserted alongside the check run.

checkSuite.key string Required

Stable, app-chosen key identifying the logical suite across attempts.

checkSuite.name string Required

Human-facing suite name.

checkSuite.detailsUrl string

Optional link to more detail about the suite as a whole.

checkSuite.externalId string Required

Provider-assigned immutable identity for this suite attempt.

checkRun object Required

The check run to upsert.

checkRun.key string Required

Stable, app-chosen key identifying the logical check across attempts.

checkRun.name string Required

Human-facing check-run name.

checkRun.status string Required

Allowed values: CHECK_RUN_LIFECYCLE_STATUS_UNSPECIFIED, queued, in_progress, completed.

checkRun.conclusion string

Required iff status == completed. Allowed values: CHECK_RUN_CONCLUSION_UNSPECIFIED, success, failure, neutral, cancelled, skipped, timed_out, action_required, stale.

checkRun.externalUpdatedAt string Required

The external system's last-update time. Used to order concurrent updates so a stale retry can't overwrite newer state.

checkRun.startedAt string

When the check run started.

checkRun.completedAt string

When the check run completed.

checkRun.detailsUrl string

Optional link to more detail about this specific check run (e.g. the provider's job/build URL).

checkRun.externalId string Required

Provider-assigned immutable identity for this check attempt.

checkRun.output object

Human-readable output for this check run.

checkRun.output.title string

Short headline for the output. Maximum length: 255 characters.

checkRun.output.summary string

Summary of the output. May contain Markdown. Maximum UTF-8 size: 65535 bytes.

checkRun.output.text string

Detailed output. May contain Markdown. Maximum UTF-8 size: 65535 bytes.

Response Fields

checkSuite object

The upserted check suite.

checkSuite.id string

Server-assigned check suite identifier.

checkSuite.repository object

Repository reference for the suite.

checkSuite.repository.id string

Repository identifier in a container reference.

checkSuite.repository.name string

Repository name in a container reference.

checkSuite.repository.owner object

Owner reference for the repository.

checkSuite.repository.owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

checkSuite.repository.owner.id string

Origin owner identifier.

checkSuite.repository.owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

checkSuite.sha string

Commit SHA to which the suite is attached.

checkSuite.key string

Stable app-chosen required-check identity. Required checks match on app plus this key, not name.

checkSuite.name string

Display-only suite name; it is not used for required-check matching.

checkSuite.detailsUrl string

Optional link to the provider's suite-level results.

checkSuite.createdAt string

RFC 3339 suite creation timestamp.

checkSuite.updatedAt string

RFC 3339 timestamp for the latest suite update.

checkSuite.externalId string

Provider identity for this suite attempt.

checkSuite.actor object

Public actor that produced the suite.

checkSuite.actor.user object

User variant of the actor. Set when a user performed the action.

checkSuite.actor.user.id string

Public identifier for the user.

checkSuite.actor.user.email string

Email address of the user. Always set when the user variant is present.

checkSuite.actor.app object

App variant of the actor. Set when an app performed the action.

checkSuite.actor.app.id string

Public identifier for the app.

checkSuite.actor.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

checkSuite.actor.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

checkSuite.actor.serviceAccount.id string

Public identifier for the service account.

checkRun object

The upserted check run.

checkRun.id string

Server-assigned check run identifier.

checkRun.repository object

Repository reference for the run.

checkRun.repository.id string

Repository identifier in a container reference.

checkRun.repository.name string

Repository name in a container reference.

checkRun.repository.owner object

Owner reference for the repository.

checkRun.repository.owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

checkRun.repository.owner.id string

Origin owner identifier.

checkRun.repository.owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

checkRun.checkSuite object

Reference to the containing check suite.

checkRun.checkSuite.id string

Server-assigned identifier of the containing check suite.

checkRun.sha string

Commit SHA to which the run is attached.

checkRun.key string

Stable app-chosen logical run identity; required checks may match on app, suite key, and this key.

checkRun.name string

Display-only run name; it is not used for required-check matching.

checkRun.status string

Lifecycle status; queued, in_progress, or completed.

checkRun.conclusion string

Required for a completed run; success, failure, neutral, cancelled, skipped, timed_out, action_required, or stale.

checkRun.detailsUrl string

Separate link to the provider's full result page.

checkRun.externalUpdatedAt string

External update timestamp used to order updates so stale retries cannot replace newer state.

checkRun.startedAt string

Provider-reported RFC 3339 start time when supplied.

checkRun.completedAt string

Provider-reported RFC 3339 completion time when supplied.

checkRun.createdAt string

RFC 3339 run creation timestamp.

checkRun.updatedAt string

RFC 3339 timestamp for the latest persisted run update.

checkRun.externalId string

Provider identity for one attempt. Reuse it to update that attempt and use a new value for a retry.

checkRun.actor object

Public actor that produced the run.

checkRun.actor.user object

User variant of the actor. Set when a user performed the action.

checkRun.actor.user.id string

Public identifier for the user.

checkRun.actor.user.email string

Email address of the user. Always set when the user variant is present.

checkRun.actor.app object

App variant of the actor. Set when an app performed the action.

checkRun.actor.app.id string

Public identifier for the app.

checkRun.actor.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

checkRun.actor.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

checkRun.actor.serviceAccount.id string

Public identifier for the service account.

checkRun.output object

Human-readable result object containing title, summary, and longer text when supplied.

checkRun.output.title string

Short headline for the output. Maximum length: 255 characters.

checkRun.output.summary string

Summary of the output. May contain Markdown. Maximum UTF-8 size: 65535 bytes.

checkRun.output.text string

Detailed output. May contain Markdown. Maximum UTF-8 size: 65535 bytes.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/check-runs' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "headSha": "HEAD_SHA",  "checkSuite": {    "key": "KEY",    "name": "NAME",    "externalId": "EXTERNAL_ID"  },  "checkRun": {    "key": "KEY",    "name": "NAME",    "status": "queued",    "externalUpdatedAt": "2026-01-01T00:00:00Z",    "externalId": "EXTERNAL_ID"  }}'

Response shape:

{  "checkSuite": {    "id": "string",    "repository": {      "id": "string",      "name": "string",      "owner": {        "slug": "string",        "id": "string",        "type": "team"      }    },    "sha": "string",    "key": "string",    "name": "string",    "detailsUrl": "string",    "createdAt": "2026-01-01T00:00:00Z",    "updatedAt": "2026-01-01T00:00:00Z",    "externalId": "string",    "actor": {      "user": {        "id": "string",        "email": "string"      }    }  },  "checkRun": {    "id": "string",    "repository": {      "id": "string",      "name": "string",      "owner": {        "slug": "string",        "id": "string",        "type": "team"      }    },    "checkSuite": {      "id": "string"    },    "sha": "string",    "key": "string",    "name": "string",    "status": "queued",    "conclusion": "success",    "detailsUrl": "string",    "externalUpdatedAt": "2026-01-01T00:00:00Z",    "startedAt": "2026-01-01T00:00:00Z",    "completedAt": "2026-01-01T00:00:00Z",    "createdAt": "2026-01-01T00:00:00Z",    "updatedAt": "2026-01-01T00:00:00Z",    "externalId": "string",    "actor": {      "user": {        "id": "string",        "email": "string"      }    },    "output": {      "title": "string",      "summary": "string",      "text": "string"    }  }}

Batch Upsert Check Runs

POST/v1/origin/repos/{ownerSlug}/{repoName}/check-runs:batchUpsert

Atomically upserts several check runs belonging to one suite. The request accepts at most 10 runs and rejects duplicate (external_id, key) identities. Every run is committed or the entire request is rolled back.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

Request Body

headSha string Required

Head commit SHA the check runs are reported against (40- or 64-char hex).

checkSuite object Required

The suite shared by every check run in this request.

checkSuite.key string Required

Stable, app-chosen key identifying the logical suite across attempts.

checkSuite.name string Required

Human-facing suite name.

checkSuite.detailsUrl string

Optional link to more detail about the suite as a whole.

checkSuite.externalId string Required

Provider-assigned immutable identity for this suite attempt.

checkRuns array Required

Check runs to upsert, in response order. Must contain 1-10 entries with unique (external_id, key) identities.

checkRuns[0].key string Required

Stable, app-chosen key identifying the logical check across attempts.

checkRuns[0].name string Required

Human-facing check-run name.

checkRuns[0].status string Required

Allowed values: CHECK_RUN_LIFECYCLE_STATUS_UNSPECIFIED, queued, in_progress, completed.

checkRuns[0].conclusion string

Required iff status == completed. Allowed values: CHECK_RUN_CONCLUSION_UNSPECIFIED, success, failure, neutral, cancelled, skipped, timed_out, action_required, stale.

checkRuns[0].externalUpdatedAt string Required

The external system's last-update time. Used to order concurrent updates so a stale retry can't overwrite newer state.

checkRuns[0].startedAt string

When the check run started.

checkRuns[0].completedAt string

When the check run completed.

checkRuns[0].detailsUrl string

Optional link to more detail about this specific check run (e.g. the provider's job/build URL).

checkRuns[0].externalId string Required

Provider-assigned immutable identity for this check attempt.

checkRuns[0].output object

Human-readable output for this check run.

checkRuns[0].output.title string

Short headline for the output. Maximum length: 255 characters.

checkRuns[0].output.summary string

Summary of the output. May contain Markdown. Maximum UTF-8 size: 65535 bytes.

checkRuns[0].output.text string

Detailed output. May contain Markdown. Maximum UTF-8 size: 65535 bytes.

Response Fields

checkSuite object

The persisted suite shared by all returned check runs.

checkSuite.id string

Server-assigned check suite identifier.

checkSuite.repository object

Repository reference for the suite.

checkSuite.repository.id string

Repository identifier in a container reference.

checkSuite.repository.name string

Repository name in a container reference.

checkSuite.repository.owner object

Owner reference for the repository.

checkSuite.repository.owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

checkSuite.repository.owner.id string

Origin owner identifier.

checkSuite.repository.owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

checkSuite.sha string

Commit SHA to which the suite is attached.

checkSuite.key string

Stable app-chosen required-check identity. Required checks match on app plus this key, not name.

checkSuite.name string

Display-only suite name; it is not used for required-check matching.

checkSuite.detailsUrl string

Optional link to the provider's suite-level results.

checkSuite.createdAt string

RFC 3339 suite creation timestamp.

checkSuite.updatedAt string

RFC 3339 timestamp for the latest suite update.

checkSuite.externalId string

Provider identity for this suite attempt.

checkSuite.actor object

Public actor that produced the suite.

checkSuite.actor.user object

User variant of the actor. Set when a user performed the action.

checkSuite.actor.user.id string

Public identifier for the user.

checkSuite.actor.user.email string

Email address of the user. Always set when the user variant is present.

checkSuite.actor.app object

App variant of the actor. Set when an app performed the action.

checkSuite.actor.app.id string

Public identifier for the app.

checkSuite.actor.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

checkSuite.actor.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

checkSuite.actor.serviceAccount.id string

Public identifier for the service account.

checkRuns array

Persisted check runs in the same order as the request.

checkRuns[].id string

Server-assigned check run identifier.

checkRuns[].repository object

Repository reference for the run.

checkRuns[].repository.id string

Repository identifier in a container reference.

checkRuns[].repository.name string

Repository name in a container reference.

checkRuns[].repository.owner object

Owner reference for the repository.

checkRuns[].repository.owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

checkRuns[].repository.owner.id string

Origin owner identifier.

checkRuns[].repository.owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

checkRuns[].checkSuite object

Reference to the containing check suite.

checkRuns[].checkSuite.id string

Server-assigned identifier of the containing check suite.

checkRuns[].sha string

Commit SHA to which the run is attached.

checkRuns[].key string

Stable app-chosen logical run identity; required checks may match on app, suite key, and this key.

checkRuns[].name string

Display-only run name; it is not used for required-check matching.

checkRuns[].status string

Lifecycle status; queued, in_progress, or completed.

checkRuns[].conclusion string

Required for a completed run; success, failure, neutral, cancelled, skipped, timed_out, action_required, or stale.

checkRuns[].detailsUrl string

Separate link to the provider's full result page.

checkRuns[].externalUpdatedAt string

External update timestamp used to order updates so stale retries cannot replace newer state.

checkRuns[].startedAt string

Provider-reported RFC 3339 start time when supplied.

checkRuns[].completedAt string

Provider-reported RFC 3339 completion time when supplied.

checkRuns[].createdAt string

RFC 3339 run creation timestamp.

checkRuns[].updatedAt string

RFC 3339 timestamp for the latest persisted run update.

checkRuns[].externalId string

Provider identity for one attempt. Reuse it to update that attempt and use a new value for a retry.

checkRuns[].actor object

Public actor that produced the run.

checkRuns[].actor.user object

User variant of the actor. Set when a user performed the action.

checkRuns[].actor.user.id string

Public identifier for the user.

checkRuns[].actor.user.email string

Email address of the user. Always set when the user variant is present.

checkRuns[].actor.app object

App variant of the actor. Set when an app performed the action.

checkRuns[].actor.app.id string

Public identifier for the app.

checkRuns[].actor.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

checkRuns[].actor.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

checkRuns[].actor.serviceAccount.id string

Public identifier for the service account.

checkRuns[].output object

Human-readable result object containing title, summary, and longer text when supplied.

checkRuns[].output.title string

Short headline for the output. Maximum length: 255 characters.

checkRuns[].output.summary string

Summary of the output. May contain Markdown. Maximum UTF-8 size: 65535 bytes.

checkRuns[].output.text string

Detailed output. May contain Markdown. Maximum UTF-8 size: 65535 bytes.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/check-runs:batchUpsert' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "headSha": "HEAD_SHA",  "checkSuite": {    "key": "KEY",    "name": "NAME",    "externalId": "EXTERNAL_ID"  },  "checkRuns": [    {      "key": "KEY",      "name": "NAME",      "status": "queued",      "externalUpdatedAt": "2026-01-01T00:00:00Z",      "externalId": "EXTERNAL_ID"    }  ]}'

Response shape:

{  "checkSuite": {    "id": "string",    "repository": {      "id": "string",      "name": "string",      "owner": {        "slug": "string",        "id": "string",        "type": "team"      }    },    "sha": "string",    "key": "string",    "name": "string",    "detailsUrl": "string",    "createdAt": "2026-01-01T00:00:00Z",    "updatedAt": "2026-01-01T00:00:00Z",    "externalId": "string",    "actor": {      "user": {        "id": "string",        "email": "string"      }    }  },  "checkRuns": [    {      "id": "string",      "repository": {        "id": "string",        "name": "string",        "owner": {          "slug": "string",          "id": "string",          "type": "team"        }      },      "checkSuite": {        "id": "string"      },      "sha": "string",      "key": "string",      "name": "string",      "status": "queued",      "conclusion": "success",      "detailsUrl": "string",      "externalUpdatedAt": "2026-01-01T00:00:00Z",      "startedAt": "2026-01-01T00:00:00Z",      "completedAt": "2026-01-01T00:00:00Z",      "createdAt": "2026-01-01T00:00:00Z",      "updatedAt": "2026-01-01T00:00:00Z",      "externalId": "string",      "actor": {        "user": {          "id": "string",          "email": "string"        }      },      "output": {        "title": "string",        "summary": "string",        "text": "string"      }    }  ]}

Get Check Run

GET/v1/origin/repos/{ownerSlug}/{repoName}/check-runs/{checkRunId}

Returns a single check run by server-assigned id (cr_...).

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

checkRunId string Required

Server-assigned check-run id (cr_...).

Response Fields

id string

Server-assigned check run identifier.

repository object

Repository reference for the run.

repository.id string

Repository identifier in a container reference.

repository.name string

Repository name in a container reference.

repository.owner object

Owner reference for the repository.

repository.owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

repository.owner.id string

Origin owner identifier.

repository.owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

checkSuite object

Reference to the containing check suite.

checkSuite.id string

Server-assigned identifier of the containing check suite.

sha string

Commit SHA to which the run is attached.

key string

Stable app-chosen logical run identity; required checks may match on app, suite key, and this key.

name string

Display-only run name; it is not used for required-check matching.

status string

Lifecycle status; queued, in_progress, or completed.

conclusion string

Required for a completed run; success, failure, neutral, cancelled, skipped, timed_out, action_required, or stale.

detailsUrl string

Separate link to the provider's full result page.

externalUpdatedAt string

External update timestamp used to order updates so stale retries cannot replace newer state.

startedAt string

Provider-reported RFC 3339 start time when supplied.

completedAt string

Provider-reported RFC 3339 completion time when supplied.

createdAt string

RFC 3339 run creation timestamp.

updatedAt string

RFC 3339 timestamp for the latest persisted run update.

externalId string

Provider identity for one attempt. Reuse it to update that attempt and use a new value for a retry.

actor object

Public actor that produced the run.

actor.user object

User variant of the actor. Set when a user performed the action.

actor.user.id string

Public identifier for the user.

actor.user.email string

Email address of the user. Always set when the user variant is present.

actor.app object

App variant of the actor. Set when an app performed the action.

actor.app.id string

Public identifier for the app.

actor.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

actor.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

actor.serviceAccount.id string

Public identifier for the service account.

output object

Human-readable result object containing title, summary, and longer text when supplied.

output.title string

Short headline for the output. Maximum length: 255 characters.

output.summary string

Summary of the output. May contain Markdown. Maximum UTF-8 size: 65535 bytes.

output.text string

Detailed output. May contain Markdown. Maximum UTF-8 size: 65535 bytes.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/check-runs/CHECK_RUN_ID' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "id": "string",  "repository": {    "id": "string",    "name": "string",    "owner": {      "slug": "string",      "id": "string",      "type": "team"    }  },  "checkSuite": {    "id": "string"  },  "sha": "string",  "key": "string",  "name": "string",  "status": "queued",  "conclusion": "success",  "detailsUrl": "string",  "externalUpdatedAt": "2026-01-01T00:00:00Z",  "startedAt": "2026-01-01T00:00:00Z",  "completedAt": "2026-01-01T00:00:00Z",  "createdAt": "2026-01-01T00:00:00Z",  "updatedAt": "2026-01-01T00:00:00Z",  "externalId": "string",  "actor": {    "user": {      "id": "string",      "email": "string"    }  },  "output": {    "title": "string",    "summary": "string",    "text": "string"  }}

List Check Run Annotations

GET/v1/origin/repos/{ownerSlug}/{repoName}/check-runs/{checkRunId}/annotations

Lists a check run's annotations in ascending ID order.

Annotation IDs are time-sortable, so ascending ID order is also creation order. A page token fixes the page size and scope for the rest of the sequence, so pageSize is ignored once you send one.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

checkRunId string Required

Server-assigned check run ID.

Query Parameters

pageSize integer

Maximum annotations to return. Defaults to 30 when omitted or zero; values above 100 are clamped to 100.

pageToken string

Opaque cursor from a previous response's nextPageToken. Omit for the first page.

Response Fields

annotations array

Page of annotations, in ascending ID order.

annotations[].id string

Stable Origin annotation ID. IDs are time-sortable.

annotations[].checkRunId string

ID of the check run the annotation belongs to.

annotations[].annotationLevel string

Severity of the annotation. Allowed values: notice, warning, failure.

annotations[].message string

Annotation message.

annotations[].title string

Annotation title. Absent when the annotation has none.

annotations[].rawDetails string

Raw detail text. Absent when the annotation has none.

annotations[].createdAt string

When the annotation was created (RFC 3339).

annotations[].updatedAt string

When the annotation was last updated (RFC 3339).

annotations[].location object

Source location. Absent for a run-level annotation.

annotations[].location.path string

Canonical repository-relative file path.

annotations[].location.startLine integer

First line of the range. 1-based and inclusive.

annotations[].location.endLine integer

Last line of the range. 1-based and inclusive.

annotations[].location.columns object

Column range. Absent unless the annotation covers a single line.

annotations[].location.columns.startColumn integer

First column of the range. 1-based and inclusive.

annotations[].location.columns.endColumn integer

Last column of the range. 1-based and inclusive.

nextPageToken string

Opaque cursor for the next page. Empty when there are no more results.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/check-runs/CHECK_RUN_ID/annotations' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "annotations": [    {      "id": "string",      "checkRunId": "string",      "annotationLevel": "warning",      "message": "string",      "title": "string",      "rawDetails": "string",      "createdAt": "2026-01-01T00:00:00Z",      "updatedAt": "2026-01-01T00:00:00Z",      "location": {        "path": "string",        "startLine": 0,        "endLine": 0,        "columns": {          "startColumn": 0,          "endColumn": 0        }      }    }  ],  "nextPageToken": "string"}

Create Check Run Annotations

POST/v1/origin/repos/{ownerSlug}/{repoName}/check-runs/{checkRunId}/annotations

Appends between 1 and 25 annotations to a check run in a single atomic batch.

A check run holds at most 100 annotations. A batch that would take it past that limit is rejected with ResourceExhausted (HTTP 429) and nothing is written; a batch outside the 1 to 25 range is rejected with InvalidArgument (HTTP 400). The operation is append-only and is not idempotent, so retrying after an ambiguous transport failure can append duplicates and consume capacity. Identical content is allowed.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

checkRunId string Required

Server-assigned check run ID.

Request Body

annotations array Required

The batch to append. Must contain between 1 and 25 entries.

annotations[].annotationLevel string Required

Severity of the annotation. Allowed values: notice, warning, failure.

annotations[].message string Required

Annotation message. Must be non-empty. Maximum 65,535 bytes of UTF-8.

annotations[].title string

Annotation title. Maximum length: 255 Unicode characters.

annotations[].rawDetails string

Raw detail text. Maximum 65,535 bytes of UTF-8.

annotations[].location object

Source location the annotation points at. Omit for a run-level annotation that is not tied to a line of code.

annotations[].location.path string Required

Canonical repository-relative file path. Maximum 4,096 bytes of UTF-8.

annotations[].location.startLine integer Required

First line of the range. 1-based and inclusive.

annotations[].location.endLine integer Required

Last line of the range. 1-based and inclusive, and at or after startLine.

annotations[].location.columns object

Column range within the line. Supported only when startLine and endLine are the same line, and both columns must be sent together.

annotations[].location.columns.startColumn integer

First column of the range. 1-based and inclusive.

annotations[].location.columns.endColumn integer

Last column of the range. 1-based and inclusive, and at or after startColumn.

Response Fields

annotations array

The annotations created by this request.

annotations[].id string

Stable Origin annotation ID. IDs are time-sortable.

annotations[].checkRunId string

ID of the check run the annotation belongs to.

annotations[].annotationLevel string

Severity of the annotation. Allowed values: notice, warning, failure.

annotations[].message string

Annotation message.

annotations[].title string

Annotation title. Absent when the annotation has none.

annotations[].rawDetails string

Raw detail text. Absent when the annotation has none.

annotations[].createdAt string

When the annotation was created (RFC 3339).

annotations[].updatedAt string

When the annotation was last updated (RFC 3339).

annotations[].location object

Source location. Absent for a run-level annotation.

annotations[].location.path string

Canonical repository-relative file path.

annotations[].location.startLine integer

First line of the range. 1-based and inclusive.

annotations[].location.endLine integer

Last line of the range. 1-based and inclusive.

annotations[].location.columns object

Column range. Absent unless the annotation covers a single line.

annotations[].location.columns.startColumn integer

First column of the range. 1-based and inclusive.

annotations[].location.columns.endColumn integer

Last column of the range. 1-based and inclusive.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/check-runs/CHECK_RUN_ID/annotations' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "annotations": [    {      "annotationLevel": "warning",      "message": "MESSAGE",      "location": {        "path": "src/index.ts",        "startLine": 12,        "endLine": 12      }    }  ]}'

Response shape:

{  "annotations": [    {      "id": "string",      "checkRunId": "string",      "annotationLevel": "warning",      "message": "string",      "title": "string",      "rawDetails": "string",      "createdAt": "2026-01-01T00:00:00Z",      "updatedAt": "2026-01-01T00:00:00Z",      "location": {        "path": "string",        "startLine": 0,        "endLine": 0,        "columns": {          "startColumn": 0,          "endColumn": 0        }      }    }  ]}

Get Check Suite

GET/v1/origin/repos/{ownerSlug}/{repoName}/check-suites/{checkSuiteId}

Returns check suite metadata by server-assigned id (crg_...). Does not embed check runs; use ListCheckRunsForSuite for the suite's runs.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

checkSuiteId string Required

Server-assigned check suite id (crg_...).

Response Fields

id string

Server-assigned check suite identifier.

repository object

Repository reference for the suite.

repository.id string

Repository identifier in a container reference.

repository.name string

Repository name in a container reference.

repository.owner object

Owner reference for the repository.

repository.owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

repository.owner.id string

Origin owner identifier.

repository.owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

sha string

Commit SHA to which the suite is attached.

key string

Stable app-chosen required-check identity. Required checks match on app plus this key, not name.

name string

Display-only suite name; it is not used for required-check matching.

detailsUrl string

Optional link to the provider's suite-level results.

createdAt string

RFC 3339 suite creation timestamp.

updatedAt string

RFC 3339 timestamp for the latest suite update.

externalId string

Provider identity for this suite attempt.

actor object

Public actor that produced the suite.

actor.user object

User variant of the actor. Set when a user performed the action.

actor.user.id string

Public identifier for the user.

actor.user.email string

Email address of the user. Always set when the user variant is present.

actor.app object

App variant of the actor. Set when an app performed the action.

actor.app.id string

Public identifier for the app.

actor.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

actor.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

actor.serviceAccount.id string

Public identifier for the service account.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/check-suites/CHECK_SUITE_ID' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "id": "string",  "repository": {    "id": "string",    "name": "string",    "owner": {      "slug": "string",      "id": "string",      "type": "team"    }  },  "sha": "string",  "key": "string",  "name": "string",  "detailsUrl": "string",  "createdAt": "2026-01-01T00:00:00Z",  "updatedAt": "2026-01-01T00:00:00Z",  "externalId": "string",  "actor": {    "user": {      "id": "string",      "email": "string"    }  }}

List Check Runs For Suite

GET/v1/origin/repos/{ownerSlug}/{repoName}/check-suites/{checkSuiteId}/check-runs

Lists check runs belonging to a suite. Paginated.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

checkSuiteId string Required

Server-assigned check suite id (crg_...).

Query Parameters

pageSize integer

Max check runs to return. Defaults to 30 when unset or 0. Values above 100 are clamped to 100.

pageToken string

Opaque cursor from a previous response's next_page_token. Empty for the first page. Encodes the last-seen check-run id scoped to this suite, so page_size on a follow-up request is ignored when a token is supplied.

Response Fields

checkRuns array

Paginated check runs belonging to the named suite.

checkRuns[].id string

Server-assigned check run identifier.

checkRuns[].repository object

Repository reference for the run.

checkRuns[].repository.id string

Repository identifier in a container reference.

checkRuns[].repository.name string

Repository name in a container reference.

checkRuns[].repository.owner object

Owner reference for the repository.

checkRuns[].repository.owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

checkRuns[].repository.owner.id string

Origin owner identifier.

checkRuns[].repository.owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

checkRuns[].checkSuite object

Reference to the containing check suite.

checkRuns[].checkSuite.id string

Server-assigned identifier of the containing check suite.

checkRuns[].sha string

Commit SHA to which the run is attached.

checkRuns[].key string

Stable app-chosen logical run identity; required checks may match on app, suite key, and this key.

checkRuns[].name string

Display-only run name; it is not used for required-check matching.

checkRuns[].status string

Lifecycle status; queued, in_progress, or completed.

checkRuns[].conclusion string

Required for a completed run; success, failure, neutral, cancelled, skipped, timed_out, action_required, or stale.

checkRuns[].detailsUrl string

Separate link to the provider's full result page.

checkRuns[].externalUpdatedAt string

External update timestamp used to order updates so stale retries cannot replace newer state.

checkRuns[].startedAt string

Provider-reported RFC 3339 start time when supplied.

checkRuns[].completedAt string

Provider-reported RFC 3339 completion time when supplied.

checkRuns[].createdAt string

RFC 3339 run creation timestamp.

checkRuns[].updatedAt string

RFC 3339 timestamp for the latest persisted run update.

checkRuns[].externalId string

Provider identity for one attempt. Reuse it to update that attempt and use a new value for a retry.

checkRuns[].actor object

Public actor that produced the run.

checkRuns[].actor.user object

User variant of the actor. Set when a user performed the action.

checkRuns[].actor.user.id string

Public identifier for the user.

checkRuns[].actor.user.email string

Email address of the user. Always set when the user variant is present.

checkRuns[].actor.app object

App variant of the actor. Set when an app performed the action.

checkRuns[].actor.app.id string

Public identifier for the app.

checkRuns[].actor.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

checkRuns[].actor.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

checkRuns[].actor.serviceAccount.id string

Public identifier for the service account.

checkRuns[].output object

Human-readable result object containing title, summary, and longer text when supplied.

checkRuns[].output.title string

Short headline for the output. Maximum length: 255 characters.

checkRuns[].output.summary string

Summary of the output. May contain Markdown. Maximum UTF-8 size: 65535 bytes.

checkRuns[].output.text string

Detailed output. May contain Markdown. Maximum UTF-8 size: 65535 bytes.

nextPageToken string

Opaque cursor for the next page; empty when there are no more pages.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/check-suites/CHECK_SUITE_ID/check-runs' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "checkRuns": [    {      "id": "string",      "repository": {        "id": "string",        "name": "string",        "owner": {          "slug": "string",          "id": "string",          "type": "team"        }      },      "checkSuite": {        "id": "string"      },      "sha": "string",      "key": "string",      "name": "string",      "status": "queued",      "conclusion": "success",      "detailsUrl": "string",      "externalUpdatedAt": "2026-01-01T00:00:00Z",      "startedAt": "2026-01-01T00:00:00Z",      "completedAt": "2026-01-01T00:00:00Z",      "createdAt": "2026-01-01T00:00:00Z",      "updatedAt": "2026-01-01T00:00:00Z",      "externalId": "string",      "actor": {        "user": {          "id": "string",          "email": "string"        }      },      "output": {        "title": "string",        "summary": "string",        "text": "string"      }    }  ],  "nextPageToken": "string"}

List Check Runs For Commit

GET/v1/origin/repos/{ownerSlug}/{repoName}/commits/{sha}/check-runs

Lists every check run reported against a commit, across all suites. Paginated.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

sha string Required

Commit SHA (40- or 64-char hex) to list check runs for.

Query Parameters

pageSize integer

Max check runs to return. Defaults to 30 when unset or 0. Values above 100 are clamped to 100.

pageToken string

Opaque cursor from a previous response's next_page_token. Empty for the first page. Encodes the last-seen check-run id scoped to this commit, so page_size on a follow-up request is ignored when a token is supplied.

Response Fields

checkRuns array

Paginated check runs attached to the resolved commit SHA.

checkRuns[].id string

Server-assigned check run identifier.

checkRuns[].repository object

Repository reference for the run.

checkRuns[].repository.id string

Repository identifier in a container reference.

checkRuns[].repository.name string

Repository name in a container reference.

checkRuns[].repository.owner object

Owner reference for the repository.

checkRuns[].repository.owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

checkRuns[].repository.owner.id string

Origin owner identifier.

checkRuns[].repository.owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

checkRuns[].checkSuite object

Reference to the containing check suite.

checkRuns[].checkSuite.id string

Server-assigned identifier of the containing check suite.

checkRuns[].sha string

Commit SHA to which the run is attached.

checkRuns[].key string

Stable app-chosen logical run identity; required checks may match on app, suite key, and this key.

checkRuns[].name string

Display-only run name; it is not used for required-check matching.

checkRuns[].status string

Lifecycle status; queued, in_progress, or completed.

checkRuns[].conclusion string

Required for a completed run; success, failure, neutral, cancelled, skipped, timed_out, action_required, or stale.

checkRuns[].detailsUrl string

Separate link to the provider's full result page.

checkRuns[].externalUpdatedAt string

External update timestamp used to order updates so stale retries cannot replace newer state.

checkRuns[].startedAt string

Provider-reported RFC 3339 start time when supplied.

checkRuns[].completedAt string

Provider-reported RFC 3339 completion time when supplied.

checkRuns[].createdAt string

RFC 3339 run creation timestamp.

checkRuns[].updatedAt string

RFC 3339 timestamp for the latest persisted run update.

checkRuns[].externalId string

Provider identity for one attempt. Reuse it to update that attempt and use a new value for a retry.

checkRuns[].actor object

Public actor that produced the run.

checkRuns[].actor.user object

User variant of the actor. Set when a user performed the action.

checkRuns[].actor.user.id string

Public identifier for the user.

checkRuns[].actor.user.email string

Email address of the user. Always set when the user variant is present.

checkRuns[].actor.app object

App variant of the actor. Set when an app performed the action.

checkRuns[].actor.app.id string

Public identifier for the app.

checkRuns[].actor.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

checkRuns[].actor.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

checkRuns[].actor.serviceAccount.id string

Public identifier for the service account.

checkRuns[].output object

Human-readable result object containing title, summary, and longer text when supplied.

checkRuns[].output.title string

Short headline for the output. Maximum length: 255 characters.

checkRuns[].output.summary string

Summary of the output. May contain Markdown. Maximum UTF-8 size: 65535 bytes.

checkRuns[].output.text string

Detailed output. May contain Markdown. Maximum UTF-8 size: 65535 bytes.

nextPageToken string

Opaque cursor for the next page; empty when there are no more pages.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/commits/SHA/check-runs' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "checkRuns": [    {      "id": "string",      "repository": {        "id": "string",        "name": "string",        "owner": {          "slug": "string",          "id": "string",          "type": "team"        }      },      "checkSuite": {        "id": "string"      },      "sha": "string",      "key": "string",      "name": "string",      "status": "queued",      "conclusion": "success",      "detailsUrl": "string",      "externalUpdatedAt": "2026-01-01T00:00:00Z",      "startedAt": "2026-01-01T00:00:00Z",      "completedAt": "2026-01-01T00:00:00Z",      "createdAt": "2026-01-01T00:00:00Z",      "updatedAt": "2026-01-01T00:00:00Z",      "externalId": "string",      "actor": {        "user": {          "id": "string",          "email": "string"        }      },      "output": {        "title": "string",        "summary": "string",        "text": "string"      }    }  ],  "nextPageToken": "string"}

List Check Suites For Commit

GET/v1/origin/repos/{ownerSlug}/{repoName}/commits/{sha}/check-suites

Lists check suites reported against a commit. Returns suite metadata only (no embedded runs). Paginated.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

sha string Required

Commit SHA (40- or 64-char hex) to list suites for.

Query Parameters

pageSize integer

Max suites to return. Defaults to 30 when unset or 0. Values above 100 are clamped to 100.

pageToken string

Opaque cursor from a previous response's next_page_token. Empty for the first page. Encodes the last-seen check-suite id scoped to this commit, so page_size on a follow-up request is ignored when a token is supplied.

Response Fields

checkSuites array

Paginated check suites attached to the resolved commit SHA.

checkSuites[].id string

Server-assigned check suite identifier.

checkSuites[].repository object

Repository reference for the suite.

checkSuites[].repository.id string

Repository identifier in a container reference.

checkSuites[].repository.name string

Repository name in a container reference.

checkSuites[].repository.owner object

Owner reference for the repository.

checkSuites[].repository.owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

checkSuites[].repository.owner.id string

Origin owner identifier.

checkSuites[].repository.owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

checkSuites[].sha string

Commit SHA to which the suite is attached.

checkSuites[].key string

Stable app-chosen required-check identity. Required checks match on app plus this key, not name.

checkSuites[].name string

Display-only suite name; it is not used for required-check matching.

checkSuites[].detailsUrl string

Optional link to the provider's suite-level results.

checkSuites[].createdAt string

RFC 3339 suite creation timestamp.

checkSuites[].updatedAt string

RFC 3339 timestamp for the latest suite update.

checkSuites[].externalId string

Provider identity for this suite attempt.

checkSuites[].actor object

Public actor that produced the suite.

checkSuites[].actor.user object

User variant of the actor. Set when a user performed the action.

checkSuites[].actor.user.id string

Public identifier for the user.

checkSuites[].actor.user.email string

Email address of the user. Always set when the user variant is present.

checkSuites[].actor.app object

App variant of the actor. Set when an app performed the action.

checkSuites[].actor.app.id string

Public identifier for the app.

checkSuites[].actor.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

checkSuites[].actor.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

checkSuites[].actor.serviceAccount.id string

Public identifier for the service account.

nextPageToken string

Opaque cursor for the next page; empty when there are no more pages.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/commits/SHA/check-suites' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "checkSuites": [    {      "id": "string",      "repository": {        "id": "string",        "name": "string",        "owner": {          "slug": "string",          "id": "string",          "type": "team"        }      },      "sha": "string",      "key": "string",      "name": "string",      "detailsUrl": "string",      "createdAt": "2026-01-01T00:00:00Z",      "updatedAt": "2026-01-01T00:00:00Z",      "externalId": "string",      "actor": {        "user": {          "id": "string",          "email": "string"        }      }    }  ],  "nextPageToken": "string"}

Commits and contents

A commit separates git-object metadata under commit from top-level repository relationships. List responses omit stats; Get Commit includes whole-commit aggregate stats. Changed files are returned only by the paginated List Commit Files collection. author and committer are git identities recorded in the commit, not Origin user objects.

A comparison is a summary only: it never embeds commit lists or file diffs. status is exactly identical, ahead, behind, or diverged; aheadBy and behindBy are commit counts. baseCommit, headCommit, and mergeBaseCommit use the sparse commit projection (no stats or files).

List Commits

GET/v1/origin/repos/{ownerSlug}/{repoName}/commits

Lists commits on a branch or starting ref.

List results omit stats. Use Get Commit for aggregate stats and List Commit Files for the paginated file diff.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

Query Parameters

sha string

SHA, branch, tag, or symbolic ref (for example HEAD) to start listing from. Empty means the repo's default branch.

pageSize integer

Max commits to return. Defaults to 30 when unset or 0. Values above 100 are clamped to 100.

pageToken string

Opaque cursor from a previous response's next_page_token. Empty for the first page. Encodes the starting ref and page, so sha/page_size on a follow-up request are ignored when a token is supplied.

Response Fields

commits array

Sparse commits with no stats; changed files are not embedded.

commits[].sha string

Full commit SHA.

commits[].commit object

Git-object metadata nested separately from top-level repository relationships.

commits[].commit.author object

Git author identity recorded in the commit, not an Origin user object.

commits[].commit.author.name string

Name recorded in the Git author identity.

commits[].commit.author.email string

Email recorded in the Git author identity.

commits[].commit.author.date string

RFC 3339 date recorded in the Git author identity.

commits[].commit.committer object

Git committer identity recorded in the commit, not an Origin user object.

commits[].commit.committer.name string

Name recorded in the Git identity.

commits[].commit.committer.email string

Email recorded in the Git identity.

commits[].commit.committer.date string

ISO-8601 timestamp preserving the git signature's original timezone offset (e.g. "2014-11-07T22:01:45+01:00").

commits[].commit.message string

Commit message.

commits[].commit.tree object

Tree referenced by the commit.

commits[].commit.tree.sha string

SHA of the tree referenced by the commit.

commits[].parents array

Parent commit references, each containing a SHA.

commits[].parents[].sha string

Parent commit SHA.

nextPageToken string

Opaque cursor for the next page; empty when there are no more pages.

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

Response shape:

{  "commits": [    {      "sha": "string",      "commit": {        "author": {          "name": "string",          "email": "string",          "date": "string"        },        "committer": {          "name": "string",          "email": "string",          "date": "string"        },        "message": "string",        "tree": {          "sha": "string"        }      },      "parents": [        {          "sha": "string"        }      ]    }  ],  "nextPageToken": "string"}

Get Commit

GET/v1/origin/repos/{ownerSlug}/{repoName}/commits/{sha}

Returns a single commit by SHA or ref with whole-commit aggregate stats. It does not include changed files; use List Commit Files.

author and committer are git identities recorded in the commit, not Origin user objects.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

sha string Required

SHA, branch, tag, or symbolic ref (for example HEAD) of the commit to fetch.

Response Fields

sha string

Full commit SHA.

commit object

Git-object metadata nested separately from top-level repository relationships.

commit.author object

Git author identity recorded in the commit, not an Origin user object.

commit.author.name string

Name recorded in the Git author identity.

commit.author.email string

Email recorded in the Git author identity.

commit.author.date string

RFC 3339 date recorded in the Git author identity.

commit.committer object

Git committer identity recorded in the commit, not an Origin user object.

commit.committer.name string

Name recorded in the Git identity.

commit.committer.email string

Email recorded in the Git identity.

commit.committer.date string

ISO-8601 timestamp preserving the git signature's original timezone offset (e.g. "2014-11-07T22:01:45+01:00").

commit.message string

Commit message.

commit.tree object

Tree referenced by the commit.

commit.tree.sha string

SHA of the tree referenced by the commit.

parents array

Parent commit references, each containing a SHA.

parents[].sha string

Parent commit SHA.

stats object

Whole-commit aggregate additions, deletions, and total; included by get-commit and omitted by list projections.

stats.additions integer

Aggregate added lines for the commit.

stats.deletions integer

Aggregate deleted lines for the commit.

stats.total integer

Aggregate additions plus deletions for the commit.

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

Response shape:

{  "sha": "string",  "commit": {    "author": {      "name": "string",      "email": "string",      "date": "string"    },    "committer": {      "name": "string",      "email": "string",      "date": "string"    },    "message": "string",    "tree": {      "sha": "string"    }  },  "parents": [    {      "sha": "string"    }  ],  "stats": {    "additions": 0,    "deletions": 0,    "total": 0  }}

List Commit Files

GET/v1/origin/repos/{ownerSlug}/{repoName}/commits/{sha}/files

Lists the files changed by a commit.

sha may be a commit SHA, branch, tag, or symbolic ref such as HEAD. Results default to 30 files and are capped at 100. A page token fixes the resolved commit, page size, and file cursor; on later requests, sha and pageSize must match the token. Each file includes filename, status, additions, deletions, changes, patch, and previousFilename when renamed or copied. patch is empty for binary files.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

sha string Required

SHA, branch, tag, or symbolic ref (for example HEAD) of the commit whose files should be listed.

Query Parameters

pageSize integer

Max changed files to return. Defaults to 30 when unset or 0. Values above 100 are clamped to 100.

pageToken string

Opaque cursor from a previous response's next_page_token. Empty for the first page. The token fixes the resolved commit, page size, and file cursor, so sha and page_size on a follow-up request must match the token.

Response Fields

files array

Paginated changed files with filename, status, line counts, patch, and previousFilename for renamed or copied files. Binary patches are empty.

files[].filename string

Path of the changed file.

files[].status string

Change status; added, removed, modified, renamed, or copied.

files[].additions integer

Added line count for the file.

files[].deletions integer

Deleted line count for the file.

files[].changes integer

Total changed line count for the file.

files[].patch string

Unified patch; empty for binary files.

files[].previousFilename string

Previous path when the file was renamed or copied.

nextPageToken string

Token fixes the resolved commit, page size, and file cursor; subsequent sha and pageSize values must match it.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/commits/SHA/files' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "files": [    {      "filename": "string",      "status": "string",      "additions": 0,      "deletions": 0,      "changes": 0,      "patch": "string",      "previousFilename": "string"    }  ],  "nextPageToken": "string"}

Compare Commits

GET/v1/origin/repos/{ownerSlug}/{repoName}/compare/{basehead}

Compares commits, refs, or tags relative to their merge base. basehead is "{base}...{head}"; refs containing "/" must use their SHA.

base and head may each be a SHA, branch, tag, or symbolic ref such as HEAD. The response is an unpaginated summary: status is identical, ahead, behind, or diverged; the three commit objects are sparse and omit stats and files. No totalCommits, embedded commits, or files fields are returned. Unrelated histories return 404.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

basehead string Required

"{base}...{head}", where either revision may be a SHA, branch, tag, or symbolic ref such as HEAD.

Response Fields

status string

Comparison state; exactly identical, ahead, behind, or diverged.

aheadBy integer

Number of commits by which the head is ahead.

behindBy integer

Number of commits by which the head is behind.

baseCommit object

Sparse resolved base commit with no stats or files.

baseCommit.sha string

Full commit SHA.

baseCommit.commit object

Git-object metadata nested separately from top-level repository relationships.

baseCommit.commit.author object

Git author identity recorded in the commit, not an Origin user object.

baseCommit.commit.author.name string

Name recorded in the Git author identity.

baseCommit.commit.author.email string

Email recorded in the Git author identity.

baseCommit.commit.author.date string

RFC 3339 date recorded in the Git author identity.

baseCommit.commit.committer object

Git committer identity recorded in the commit, not an Origin user object.

baseCommit.commit.committer.name string

Name recorded in the Git identity.

baseCommit.commit.committer.email string

Email recorded in the Git identity.

baseCommit.commit.committer.date string

ISO-8601 timestamp preserving the git signature's original timezone offset (e.g. "2014-11-07T22:01:45+01:00").

baseCommit.commit.message string

Commit message.

baseCommit.commit.tree object

Tree referenced by the commit.

baseCommit.commit.tree.sha string

SHA of the tree referenced by the commit.

baseCommit.parents array

Parent commit references, each containing a SHA.

baseCommit.parents[].sha string

Parent commit SHA.

headCommit object

Sparse resolved head commit with no stats or files.

headCommit.sha string

Full commit SHA.

headCommit.commit object

Git-object metadata nested separately from top-level repository relationships.

headCommit.commit.author object

Git author identity recorded in the commit, not an Origin user object.

headCommit.commit.author.name string

Name recorded in the Git author identity.

headCommit.commit.author.email string

Email recorded in the Git author identity.

headCommit.commit.author.date string

RFC 3339 date recorded in the Git author identity.

headCommit.commit.committer object

Git committer identity recorded in the commit, not an Origin user object.

headCommit.commit.committer.name string

Name recorded in the Git identity.

headCommit.commit.committer.email string

Email recorded in the Git identity.

headCommit.commit.committer.date string

ISO-8601 timestamp preserving the git signature's original timezone offset (e.g. "2014-11-07T22:01:45+01:00").

headCommit.commit.message string

Commit message.

headCommit.commit.tree object

Tree referenced by the commit.

headCommit.commit.tree.sha string

SHA of the tree referenced by the commit.

headCommit.parents array

Parent commit references, each containing a SHA.

headCommit.parents[].sha string

Parent commit SHA.

mergeBaseCommit object

Sparse merge-base commit with no stats or files.

mergeBaseCommit.sha string

Full commit SHA.

mergeBaseCommit.commit object

Git-object metadata nested separately from top-level repository relationships.

mergeBaseCommit.commit.author object

Git author identity recorded in the commit, not an Origin user object.

mergeBaseCommit.commit.author.name string

Name recorded in the Git author identity.

mergeBaseCommit.commit.author.email string

Email recorded in the Git author identity.

mergeBaseCommit.commit.author.date string

RFC 3339 date recorded in the Git author identity.

mergeBaseCommit.commit.committer object

Git committer identity recorded in the commit, not an Origin user object.

mergeBaseCommit.commit.committer.name string

Name recorded in the Git identity.

mergeBaseCommit.commit.committer.email string

Email recorded in the Git identity.

mergeBaseCommit.commit.committer.date string

ISO-8601 timestamp preserving the git signature's original timezone offset (e.g. "2014-11-07T22:01:45+01:00").

mergeBaseCommit.commit.message string

Commit message.

mergeBaseCommit.commit.tree object

Tree referenced by the commit.

mergeBaseCommit.commit.tree.sha string

SHA of the tree referenced by the commit.

mergeBaseCommit.parents array

Parent commit references, each containing a SHA.

mergeBaseCommit.parents[].sha string

Parent commit SHA.

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

Response shape:

{  "status": "identical",  "aheadBy": 0,  "behindBy": 0,  "baseCommit": {    "sha": "string",    "commit": {      "author": {        "name": "string",        "email": "string",        "date": "string"      },      "committer": {        "name": "string",        "email": "string",        "date": "string"      },      "message": "string",      "tree": {        "sha": "string"      }    },    "parents": [      {        "sha": "string"      }    ]  },  "headCommit": {    "sha": "string",    "commit": {      "author": {        "name": "string",        "email": "string",        "date": "string"      },      "committer": {        "name": "string",        "email": "string",        "date": "string"      },      "message": "string",      "tree": {        "sha": "string"      }    },    "parents": [      {        "sha": "string"      }    ]  },  "mergeBaseCommit": {    "sha": "string",    "commit": {      "author": {        "name": "string",        "email": "string",        "date": "string"      },      "committer": {        "name": "string",        "email": "string",        "date": "string"      },      "message": "string",      "tree": {        "sha": "string"      }    },    "parents": [      {        "sha": "string"      }    ]  }}

Get Contents

GET/v1/origin/repos/{ownerSlug}/{repoName}/contents

Returns file or directory contents at a ref. The file path is passed as the path query parameter (supports nested paths); omit or leave empty for the repository root directory. Files larger than 1 MiB (decoded) are rejected with FailedPrecondition (HTTP 400).

Files contain base64 content. Directories contain immediate children in entries. Directory entries are sparse children containing type, name, path, sha, and size; fetch a child path to read its content.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

Query Parameters

path string

Path to the file or directory relative to the repository root. Empty requests the root directory.

ref string

Commit, branch, tag, or symbolic ref (for example HEAD) to read from. Empty means the repository's default branch.

Response Fields

type string

Content kind; file or dir.

encoding string

File encoding; file responses use base64.

size string

Decoded content size in bytes, encoded as a JSON string under the API's 64-bit integer convention. File payloads larger than 1 MiB are rejected.

name string

Base name of the file or directory.

path string

Path relative to the repository root.

sha string

Blob SHA for a file or tree SHA for a directory.

content string

Base64-encoded file body; present for a fetched file.

entries array

Immediate sparse children of a directory. Entries contain type, name, path, sha, and size; fetch a child path to read its content.

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

Response shape:

{  "type": "string",  "encoding": "string",  "size": "string",  "name": "string",  "path": "string",  "sha": "string",  "content": "string",  "entries": [    {      "type": "string",      "encoding": "string",      "size": "string",      "name": "string",      "path": "string",      "sha": "string",      "content": "string",      "entries": [        {          "type": "string",          "encoding": "string",          "size": "string",          "name": "string",          "path": "string",          "sha": "string",          "content": "string",          "entries": [            {}          ]        }      ]    }  ]}

Batch Get Contents

POST/v1/origin/repos/{ownerSlug}/{repoName}/contents:batchGet

Returns the contents of several explicit paths at a ref in one request. Each requested path yields a result marking whether it was found; a found path carries the same Content shape as GetContents (files as base64, directories as immediate entries, symlinks as files). Paths are matched exactly, with no globs or patterns, and at most 20 may be requested; duplicates are removed. Response results preserve first-seen request order. A single file larger than the Get Contents 1 MiB cap fails the whole batch with FailedPrecondition (HTTP 400). Uses POST because the path list travels in the request body.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

Request Body

paths array Required

Exact paths to fetch, relative to the repository root (no globs or patterns). At most 20 entries; duplicates are removed. An empty string requests the repository root directory.

ref string

Commit, branch, tag, or symbolic ref (for example HEAD) to read from. Empty means the repository's default branch.

Response Fields

results array

One result per returned exact path, preserving first-seen request order.

results[].path string

Requested path corresponding to this result.

results[].found boolean

Whether the requested path exists at the resolved commit.

results[].content object

Content value when found is true; omitted when found is false.

results[].content.type string

Content kind; file or dir.

results[].content.encoding string

File encoding; file responses use base64.

results[].content.size string

Decoded content size in bytes, encoded as a JSON string under the API's 64-bit integer convention. File payloads larger than 1 MiB are rejected.

results[].content.name string

Base name of the file or directory.

results[].content.path string

Path relative to the repository root.

results[].content.sha string

Blob SHA for a file or tree SHA for a directory.

results[].content.content string

Base64-encoded file body; present for a fetched file.

results[].content.entries array

Immediate sparse children of a directory. Entries contain type, name, path, sha, and size; fetch a child path to read its content.

resolvedCommitSha string

Commit SHA to which the requested ref resolved.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/contents:batchGet' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "paths": [    "PATH"  ]}'

Response shape:

{  "results": [    {      "path": "string",      "found": false,      "content": {        "type": "string",        "encoding": "string",        "size": "string",        "name": "string",        "path": "string",        "sha": "string",        "content": "string",        "entries": [          {}        ]      }    }  ],  "resolvedCommitSha": "string"}

Git data

Low-level git objects. Scope: repository:contents:read. Empty repositories return 409.

Get Blob

GET/v1/origin/repos/{ownerSlug}/{repoName}/git/blobs/{sha}

Returns a Git blob object by SHA. Default response is JSON with MIME-wrapped base64 content. Pass Accept: application/vnd.origin.raw+json (or application/vnd.origin.raw) on the REST surface to receive raw blob bytes instead. Blobs larger than 4 MiB (decoded) are rejected; fetch larger files by cloning the repository over Git HTTPS. Empty repositories return 409 Conflict.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

sha string Required

Full or abbreviated hex SHA of the blob object.

Response Fields

sha string

Git blob object SHA.

size integer

Decoded blob size as a JSON number; blobs larger than 4 MiB are rejected by the JSON endpoint.

encoding string

JSON blob responses use base64 encoding.

content string

Base64-encoded blob bytes; callers may request raw bytes with Accept: application/vnd.origin.raw.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/git/blobs/SHA' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "sha": "string",  "size": 0,  "encoding": "string",  "content": "string"}

Get Git Commit

GET/v1/origin/repos/{ownerSlug}/{repoName}/git/commits/{sha}

Returns a Git commit object by SHA (or resolvable revision). This is the low-level Git Database commit shape (flat author/message/tree), not the higher-level GetCommit resource under /commits/{sha}. sha accepts a commit SHA, branch, tag, or symbolic ref such as HEAD. Empty repositories return 409 Conflict.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

sha string Required

Full or abbreviated hex SHA of the commit object, or a branch, tag, or symbolic ref such as HEAD.

Response Fields

sha string

Full hex commit SHA.

author object

Author signature from the git object.

author.name string

Name recorded in the Git identity.

author.email string

Email recorded in the Git identity.

author.date string

ISO-8601 timestamp preserving the git signature's original timezone offset (e.g. "2014-11-07T22:01:45+01:00").

committer object

Committer signature from the git object.

committer.name string

Name recorded in the Git identity.

committer.email string

Email recorded in the Git identity.

committer.date string

ISO-8601 timestamp preserving the git signature's original timezone offset (e.g. "2014-11-07T22:01:45+01:00").

message string

Full commit message.

tree object

Tree this commit points at.

tree.sha string

SHA of the tree referenced by the commit.

parents array

Parent commit SHAs (empty for a root commit).

parents[].sha string

Parent commit SHA.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/git/commits/SHA' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "sha": "string",  "author": {    "name": "string",    "email": "string",    "date": "string"  },  "committer": {    "name": "string",    "email": "string",    "date": "string"  },  "message": "string",  "tree": {    "sha": "string"  },  "parents": [    {      "sha": "string"    }  ]}

Get Git Ref

GET/v1/origin/repos/{ownerSlug}/{repoName}/git/ref/{ref}

Returns a single Git reference by name. ref is typically heads/<branch> or tags/<tag> (with or without a leading refs/), or the symbolic HEAD. Exact match only; use ListMatchingGitRefs for prefixes. Empty repositories return 409 Conflict.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

ref string Required

Git reference name. Typically heads/<branch> or tags/<tag>; a leading refs/ is accepted and normalized. The symbolic HEAD is also accepted (returned as ref: "HEAD" with the tip commit). Exact match on the full ref name.

Response Fields

ref string

Full ref name, e.g. "refs/heads/main".

object object

Object this ref points at directly (unpeeled). For annotated tags, object.type is "tag" and object.sha is the tag object SHA.

object.sha string

Hex SHA of the target object.

object.type string

One of "commit", "tree", "blob", or "tag".

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/git/ref/REF' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "ref": "string",  "object": {    "sha": "string",    "type": "string"  }}

List Matching Git Refs

GET/v1/origin/repos/{ownerSlug}/{repoName}/git/matching-refs

Lists Git references whose names start with the given prefix. REST responses unwrap to a JSON array (via response_body). A trailing slash on ref is preserved (heads/ → refs/heads/). The symbolic HEAD is matched exactly (it is not under refs/). Empty repositories return 409 Conflict.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

Query Parameters

ref string

Prefix to match. Typically heads/<prefix> or tags/<prefix>; a leading refs/ is accepted and normalized. Empty lists all refs (REST binding without a trailing path segment).

Response Fields

The response is an array. Each item contains:

ref string

Full ref name, e.g. "refs/heads/main".

object object

Object this ref points at directly (unpeeled). For annotated tags, object.type is "tag" and object.sha is the tag object SHA.

object.sha string

Hex SHA of the target object.

object.type string

One of "commit", "tree", "blob", or "tag".

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/git/matching-refs' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

[  {    "ref": "string",    "object": {      "sha": "string",      "type": "string"    }  }]

List Matching Git Refs by Path

GET/v1/origin/repos/{ownerSlug}/{repoName}/git/matching-refs/{ref}

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

ref string Required

Prefix to match. Typically heads/<prefix> or tags/<prefix>; a leading refs/ is accepted and normalized. Empty lists all refs (REST binding without a trailing path segment).

Response Fields

The response is an array. Each item contains:

ref string

Full ref name, e.g. "refs/heads/main".

object object

Object this ref points at directly (unpeeled). For annotated tags, object.type is "tag" and object.sha is the tag object SHA.

object.sha string

Hex SHA of the target object.

object.type string

One of "commit", "tree", "blob", or "tag".

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/git/matching-refs/REF' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

[  {    "ref": "string",    "object": {      "sha": "string",      "type": "string"    }  }]

Get Tag

GET/v1/origin/repos/{ownerSlug}/{repoName}/git/tags/{sha}

Returns an annotated Git tag object by SHA. Lightweight tags are not tag objects and return NotFound. Empty repositories return 409 Conflict.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

sha string Required

Full or abbreviated hex SHA of the annotated tag object.

Response Fields

sha string

Tag object SHA (hex).

tag string

Tag name, e.g. "v1.0".

message string

Tag message.

tagger object

Tagger signature from the tag object.

tagger.name string

Name recorded in the Git identity.

tagger.email string

Email recorded in the Git identity.

tagger.date string

ISO-8601 timestamp preserving the git signature's original timezone offset (e.g. "2014-11-07T22:01:45+01:00").

object object

Object this tag points at.

object.sha string

Hex SHA of the target object.

object.type string

One of "commit", "tree", "blob", or "tag".

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/git/tags/SHA' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "sha": "string",  "tag": "string",  "message": "string",  "tagger": {    "name": "string",    "email": "string",    "date": "string"  },  "object": {    "sha": "string",    "type": "string"  }}

Get Tree

GET/v1/origin/repos/{ownerSlug}/{repoName}/git/trees/{sha}

Returns a Git tree object by SHA or resolvable revision. sha accepts a tree SHA, commit SHA, branch, tag, or symbolic ref such as HEAD. Set recursive=true (or 1) to walk the whole tree; omitting the parameter or passing any other value lists immediate children only. Recursive listings truncate at 100,000 entries or 7 MiB and set truncated=true. Empty repositories return 409 Conflict.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

sha string Required

Tree SHA, commit SHA, branch, tag, or symbolic ref such as HEAD.

Query Parameters

recursive boolean

When true, returns the full recursive walk of the tree. Query values true and 1 enable recursion; omitting the parameter or passing any other value (including false and 0) lists immediate children only.

Response Fields

sha string

Tree object SHA (hex).

tree array

Entries under this tree (immediate children, or the full recursive walk).

tree[].path string

Path relative to the requested tree root.

tree[].mode string

Git mode as an octal string: "100644", "100755", "040000", "120000", "160000".

tree[].type string

One of "blob", "tree", or "commit" (gitlink/submodule).

tree[].sha string

Object SHA (hex).

tree[].size integer

Blob size in bytes. Unset for trees and gitlinks. int32 ensures REST JSON emits a number; individual blobs over 2 GiB are not representable.

truncated boolean

May be true when a recursive tree listing is truncated.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/git/trees/SHA' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "sha": "string",  "tree": [    {      "path": "string",      "mode": "string",      "type": "string",      "sha": "string",      "size": 0    }  ],  "truncated": false}

Labels

A label definition belongs to one repository and is addressed by its name. Assigning labels to a pull request is a separate surface; see Set Pull Request Labels.

List Labels

GET/v1/origin/repos/{ownerSlug}/{repoName}/labels

Lists the labels defined on a repository, ordered by name.

Page tokens are bound to the repository they were minted for. A token replayed against a different repository, or any other malformed token, returns InvalidArgument (HTTP 400).

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

Query Parameters

pageSize integer

Maximum labels to return. Defaults to 30 when omitted or zero; values above 100 are clamped to 100.

pageToken string

Opaque cursor from a previous response's nextPageToken. Omit for the first page.

Response Fields

labels array

Page of label definitions, ordered by name.

labels[].id string

Public identifier for the label.

labels[].name string

Label name, unique within the repository. Names address the label in the read and write endpoints.

labels[].color string

Six-character hex color without a leading #.

labels[].description string

Label description. Absent when the label has none.

nextPageToken string

Opaque cursor for the next page. Empty when there are no more results.

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

Response shape:

{  "labels": [    {      "id": "string",      "name": "string",      "color": "string",      "description": "string"    }  ],  "nextPageToken": "string"}

Create Label

POST/v1/origin/repos/{ownerSlug}/{repoName}/labels

Creates a label on a repository.

A name already used by another label on the repository returns AlreadyExists (HTTP 409 Conflict). A color that is not six hexadecimal characters, a name longer than 50 characters, or a description longer than 255 characters returns InvalidArgument (HTTP 400).

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

Request Body

name string Required

Label name. Leading and trailing whitespace is trimmed. Maximum length: 50 characters.

color string Required

Six-character hex color without a leading #. Uppercase input is stored lowercase.

description string

Label description. Maximum length: 255 characters.

Response Fields

id string

Public identifier for the label.

name string

Label name, unique within the repository. Names address the label in the read and write endpoints.

color string

Six-character hex color without a leading #.

description string

Label description. Absent when the label has none.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/labels' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "name": "LABEL_NAME",  "color": "0e8a16"}'

Response shape:

{  "id": "string",  "name": "string",  "color": "string",  "description": "string"}

Get Label

GET/v1/origin/repos/{ownerSlug}/{repoName}/labels/{labelName}

Returns a single repository label by name.

An unknown name returns 404. An empty labelName returns InvalidArgument (HTTP 400).

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

labelName string Required

Label name. Leading and trailing whitespace is trimmed before lookup.

Response Fields

id string

Public identifier for the label.

name string

Label name, unique within the repository. Names address the label in the read and write endpoints.

color string

Six-character hex color without a leading #.

description string

Label description. Absent when the label has none.

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

Response shape:

{  "id": "string",  "name": "string",  "color": "string",  "description": "string"}

Delete Label

DELETE/v1/origin/repos/{ownerSlug}/{repoName}/labels/{labelName}

Deletes a repository label by name. The response body is empty.

Deleting a label also removes it from every pull request it was assigned to. An unknown name returns 404. An empty labelName returns InvalidArgument (HTTP 400).

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

labelName string Required

Label name. Leading and trailing whitespace is trimmed before lookup.

Response Fields

Successful requests return no response body.

curl --request DELETE \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/labels/LABEL_NAME' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response:

204 No Content

Update Label

PATCH/v1/origin/repos/{ownerSlug}/{repoName}/labels/{labelName}

Updates a repository label identified by its current name.

Omitted fields are left unchanged, and a request that omits all three returns the label as it stands. Renaming to a name another label already uses returns AlreadyExists (HTTP 409 Conflict). An unknown labelName returns 404.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

labelName string Required

Current label name. Leading and trailing whitespace is trimmed before lookup.

Request Body

name string

New label name. Leading and trailing whitespace is trimmed. Maximum length: 50 characters. Omit to leave unchanged.

color string

Six-character hex color without a leading #. Omit to leave unchanged.

description string

Label description. Maximum length: 255 characters. Omit to leave unchanged.

Response Fields

id string

Public identifier for the label.

name string

Label name, unique within the repository. Names address the label in the read and write endpoints.

color string

Six-character hex color without a leading #.

description string

Label description. Absent when the label has none.

curl --request PATCH \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/labels/LABEL_NAME' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "color": "b60205"}'

Response shape:

{  "id": "string",  "name": "string",  "color": "string",  "description": "string"}

Pull requests

Closed or merged pull requests may additionally include closedAt, mergedAt, and mergeCommitSha. Treat head.ref and base.ref as opaque Origin ref strings; they may be short branch names or fully qualified refs/heads/… values.

Review verdict is approve, request_changes, or comment. submittedAt is absent for an unsubmitted draft review. dismissal is absent while the verdict remains active. Dismissed reviews remain visible in review listings. Reviews automatically superseded by a newer decision carry a server-generated message.

Comments expose a thread reference for grouping. Create-comment requests still accept the scalar threadId command parameter when replying. First-class thread resources and resolution APIs are not part of this release.

List Pull Requests

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls

Lists pull requests in a repo, optionally filtered by head branch, base branch, author, creation-time range, and state. Each pull request includes its assigned labels.

Results come back in creation order, newest first. Set direction=asc for oldest first. Page tokens embed the filters they were minted under, so a token replayed with different filters is rejected; restart pagination when a filter changes.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

Query Parameters

head string

Optional exact branch (head-ref) filter. Omit to list across every branch.

state string

"open" | "closed" | "all". Defaults to "open".

pageSize integer

Maximum results to return. Defaults to 30; maximum 100.

pageToken string

Opaque token from the preceding page.

author string

Optional author filter. Pass a public actor ID exactly as this endpoint returns it in pullRequests[].author.user.id, pullRequests[].author.app.id, or pullRequests[].author.serviceAccount.id (user_…, app_…, or sa_…). An author with no pull requests returns an empty list. Any other value, including the shared origin-cursor-managed-actor ID, returns InvalidArgument (HTTP 400).

base string

Optional exact base-branch filter. Accepts a short name (main) or a fully qualified ref (refs/heads/main). Omit to list across every base.

direction string

Sort direction by creation order. "desc" returns newest first and is the default; "asc" returns oldest first. Any other value returns InvalidArgument (HTTP 400).

since string

Optional inclusive lower bound on creation time, as an RFC 3339 timestamp such as 2026-08-01T00:00:00Z. Returns only pull requests created at or after that instant. A malformed timestamp returns InvalidArgument (HTTP 400).

until string

Optional inclusive upper bound on creation time, in the same RFC 3339 format as since. Returns only pull requests created at or before that instant. A malformed timestamp returns InvalidArgument (HTTP 400).

Response Fields

pullRequests array

Page of PullRequest snapshots; response numbers and version numbers are JSON strings.

pullRequests[].id string

Stable Origin pull request identifier.

pullRequests[].number string

Repository-local pull request number encoded as a JSON string.

pullRequests[].state string

Pull request state; open or closed. Merged pull requests are closed with merged set true.

pullRequests[].draft boolean

Whether the pull request is a draft.

pullRequests[].merged boolean

Whether the pull request has merged.

pullRequests[].title string

Pull request title.

pullRequests[].body string

Pull request description body.

pullRequests[].head object

The source side of the change - what is being merged in.

pullRequests[].head.ref string

The ref this side points at, as Origin records it.

pullRequests[].head.sha string

Tip commit SHA of this side at the change's latest version.

pullRequests[].base object

The target side of the change — what it merges into.

pullRequests[].base.ref string

The ref this side points at, as Origin records it.

pullRequests[].base.sha string

Tip commit SHA of this side at the change's latest version.

pullRequests[].author object

Public actor that opened the pull request.

pullRequests[].author.user object

User variant of the actor. Set when a user performed the action.

pullRequests[].author.user.id string

Public identifier for the user.

pullRequests[].author.user.email string

Email address of the user. Always set when the user variant is present.

pullRequests[].author.app object

App variant of the actor. Set when an app performed the action.

pullRequests[].author.app.id string

Public identifier for the app.

pullRequests[].author.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

pullRequests[].author.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

pullRequests[].author.serviceAccount.id string

Public identifier for the service account.

pullRequests[].createdAt string

RFC 3339 pull request creation timestamp.

pullRequests[].updatedAt string

RFC 3339 timestamp for the latest pull request update.

pullRequests[].closedAt string

RFC 3339 close timestamp; may appear on closed or merged pull requests.

pullRequests[].mergedAt string

RFC 3339 merge timestamp; may appear on merged pull requests.

pullRequests[].mergeCommitSha string

Merge commit SHA; may appear after merge.

pullRequests[].additions integer

Added lines in the current pull request version.

pullRequests[].deletions integer

Deleted lines in the current pull request version.

pullRequests[].changedFiles integer

Changed file count in the current pull request version.

pullRequests[].labels array

Labels currently assigned to the pull request, sorted by name. Empty when none are assigned.

pullRequests[].labels[].id string

Public identifier for the label.

pullRequests[].labels[].name string

Label name, unique within the repository. Names address the label in the write endpoints.

pullRequests[].labels[].color string

Six-character hex color without a leading #.

pullRequests[].labels[].description string

Label description. Absent when the label has none.

pullRequests[].version object

Current numbered pull request version and its head/base SHAs.

pullRequests[].version.number string

Monotonic pull request version number encoded as a JSON string.

pullRequests[].version.headSha string

Head SHA captured by this pull request version.

pullRequests[].version.baseSha string

Base SHA captured by this pull request version.

pullRequests[].version.createdAt string

RFC 3339 timestamp for creation of this pull request version.

nextPageToken string

Opaque continuation token returned by a list response; an empty string means there is no next page. Do not inspect or construct it, and restart pagination when repository or filters change.

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

Response shape:

{  "pullRequests": [    {      "id": "string",      "number": "string",      "state": "string",      "draft": false,      "merged": false,      "title": "string",      "body": "string",      "head": {        "ref": "string",        "sha": "string"      },      "base": {        "ref": "string",        "sha": "string"      },      "author": {        "user": {          "id": "string",          "email": "string"        }      },      "createdAt": "2026-01-01T00:00:00Z",      "updatedAt": "2026-01-01T00:00:00Z",      "closedAt": "2026-01-01T00:00:00Z",      "mergedAt": "2026-01-01T00:00:00Z",      "mergeCommitSha": "string",      "additions": 0,      "deletions": 0,      "changedFiles": 0,      "labels": [        {          "id": "string",          "name": "string",          "color": "string",          "description": "string"        }      ],      "version": {        "number": "string",        "headSha": "string",        "baseSha": "string",        "createdAt": "2026-01-01T00:00:00Z"      }    }  ],  "nextPageToken": "string"}

Get Pull Request

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}

Returns a single pull request, including its assigned labels.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

Response Fields

id string

Stable Origin pull request identifier.

number string

Repository-local pull request number encoded as a JSON string.

state string

Pull request state; open or closed. Merged pull requests are closed with merged set true.

draft boolean

Whether the pull request is a draft.

merged boolean

Whether the pull request has merged.

title string

Pull request title.

body string

Pull request description body.

head object

The source side of the change - what is being merged in.

head.ref string

The ref this side points at, as Origin records it.

head.sha string

Tip commit SHA of this side at the change's latest version.

base object

The target side of the change — what it merges into.

base.ref string

The ref this side points at, as Origin records it.

base.sha string

Tip commit SHA of this side at the change's latest version.

author object

Public actor that opened the pull request.

author.user object

User variant of the actor. Set when a user performed the action.

author.user.id string

Public identifier for the user.

author.user.email string

Email address of the user. Always set when the user variant is present.

author.app object

App variant of the actor. Set when an app performed the action.

author.app.id string

Public identifier for the app.

author.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

author.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

author.serviceAccount.id string

Public identifier for the service account.

createdAt string

RFC 3339 pull request creation timestamp.

updatedAt string

RFC 3339 timestamp for the latest pull request update.

closedAt string

RFC 3339 close timestamp; may appear on closed or merged pull requests.

mergedAt string

RFC 3339 merge timestamp; may appear on merged pull requests.

mergeCommitSha string

Merge commit SHA; may appear after merge.

additions integer

Added lines in the current pull request version.

deletions integer

Deleted lines in the current pull request version.

changedFiles integer

Changed file count in the current pull request version.

labels array

Labels currently assigned to the pull request, sorted by name. Empty when none are assigned.

labels[].id string

Public identifier for the label.

labels[].name string

Label name, unique within the repository. Names address the label in the write endpoints.

labels[].color string

Six-character hex color without a leading #.

labels[].description string

Label description. Absent when the label has none.

version object

Current numbered pull request version and its head/base SHAs.

version.number string

Monotonic pull request version number encoded as a JSON string.

version.headSha string

Head SHA captured by this pull request version.

version.baseSha string

Base SHA captured by this pull request version.

version.createdAt string

RFC 3339 timestamp for creation of this pull request version.

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

Response shape:

{  "id": "string",  "number": "string",  "state": "string",  "draft": false,  "merged": false,  "title": "string",  "body": "string",  "head": {    "ref": "string",    "sha": "string"  },  "base": {    "ref": "string",    "sha": "string"  },  "author": {    "user": {      "id": "string",      "email": "string"    }  },  "createdAt": "2026-01-01T00:00:00Z",  "updatedAt": "2026-01-01T00:00:00Z",  "closedAt": "2026-01-01T00:00:00Z",  "mergedAt": "2026-01-01T00:00:00Z",  "mergeCommitSha": "string",  "additions": 0,  "deletions": 0,  "changedFiles": 0,  "labels": [    {      "id": "string",      "name": "string",      "color": "string",      "description": "string"    }  ],  "version": {    "number": "string",    "headSha": "string",    "baseSha": "string",    "createdAt": "2026-01-01T00:00:00Z"  }}

Create Pull Request

POST/v1/origin/repos/{ownerSlug}/{repoName}/pulls

Creates a pull request from head into base.

Optional parent_pull_number stacks this change on another open or draft pull request in the same repository.

A title longer than 256 characters, or a body longer than 65,536 characters, returns InvalidArgument (HTTP 400). Both limits count Unicode code points.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

Request Body

title string Required

Pull request title. Maximum length: 256 characters.

body string

Pull request body / description. Can be empty. Maximum length: 65,536 characters.

head string Required

Source branch name (the head of the change). Must resolve in the repo at call time.

base string Required

Target branch name (what the change merges into). Must resolve in the repo at call time.

draft boolean

When true, create as a draft. When false or omitted, create as open (ready for review).

parentPullNumber string

Optional parent pull request number when stacking this change on another open/draft change in the same repository.

Response Fields

id string

Stable Origin pull request identifier.

number string

Repository-local pull request number encoded as a JSON string.

state string

Pull request state; open or closed. Merged pull requests are closed with merged set true.

draft boolean

Whether the pull request is a draft.

merged boolean

Whether the pull request has merged.

title string

Pull request title.

body string

Pull request description body.

head object

The source side of the change - what is being merged in.

head.ref string

The ref this side points at, as Origin records it.

head.sha string

Tip commit SHA of this side at the change's latest version.

base object

The target side of the change — what it merges into.

base.ref string

The ref this side points at, as Origin records it.

base.sha string

Tip commit SHA of this side at the change's latest version.

author object

Public actor that opened the pull request.

author.user object

User variant of the actor. Set when a user performed the action.

author.user.id string

Public identifier for the user.

author.user.email string

Email address of the user. Always set when the user variant is present.

author.app object

App variant of the actor. Set when an app performed the action.

author.app.id string

Public identifier for the app.

author.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

author.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

author.serviceAccount.id string

Public identifier for the service account.

createdAt string

RFC 3339 pull request creation timestamp.

updatedAt string

RFC 3339 timestamp for the latest pull request update.

closedAt string

RFC 3339 close timestamp; may appear on closed or merged pull requests.

mergedAt string

RFC 3339 merge timestamp; may appear on merged pull requests.

mergeCommitSha string

Merge commit SHA; may appear after merge.

additions integer

Added lines in the current pull request version.

deletions integer

Deleted lines in the current pull request version.

changedFiles integer

Changed file count in the current pull request version.

labels array

Labels currently assigned to the pull request, sorted by name. Empty when none are assigned.

labels[].id string

Public identifier for the label.

labels[].name string

Label name, unique within the repository. Names address the label in the write endpoints.

labels[].color string

Six-character hex color without a leading #.

labels[].description string

Label description. Absent when the label has none.

version object

Current numbered pull request version and its head/base SHAs.

version.number string

Monotonic pull request version number encoded as a JSON string.

version.headSha string

Head SHA captured by this pull request version.

version.baseSha string

Base SHA captured by this pull request version.

version.createdAt string

RFC 3339 timestamp for creation of this pull request version.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "title": "TITLE",  "head": "HEAD_BRANCH",  "base": "BASE_BRANCH"}'

Response shape:

{  "id": "string",  "number": "string",  "state": "string",  "draft": false,  "merged": false,  "title": "string",  "body": "string",  "head": {    "ref": "string",    "sha": "string"  },  "base": {    "ref": "string",    "sha": "string"  },  "author": {    "user": {      "id": "string",      "email": "string"    }  },  "createdAt": "2026-01-01T00:00:00Z",  "updatedAt": "2026-01-01T00:00:00Z",  "closedAt": "2026-01-01T00:00:00Z",  "mergedAt": "2026-01-01T00:00:00Z",  "mergeCommitSha": "string",  "additions": 0,  "deletions": 0,  "changedFiles": 0,  "labels": [    {      "id": "string",      "name": "string",      "color": "string",      "description": "string"    }  ],  "version": {    "number": "string",    "headSha": "string",    "baseSha": "string",    "createdAt": "2026-01-01T00:00:00Z"  }}

Update Pull Request

PATCH/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}

Updates a pull request's title, body, base branch, and/or lifecycle state.

Omitted fields are unchanged. Present fields are applied in order: metadata, then reopen/draft/ready-for-review, then base, then close. Close runs last so a same-request retarget can still see an open change; reopen runs before base so a closed pull can be retargeted. If a later step fails, earlier steps may already have been committed.

A title longer than 256 characters, or a body longer than 65,536 characters, returns InvalidArgument (HTTP 400). Both limits count Unicode code points.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

Request Body

title string

New title. Omitted fields are left unchanged. Maximum length: 256 characters.

body string

New body / description. An empty string clears the body. Maximum length: 65,536 characters.

state string

"open" or "closed". "closed" closes the pull request. "open" without draft: true marks it ready for review, including publishing an existing draft. Merged is not writable. use MergePullRequest.

draft boolean

true marks the pull request draft; false marks it ready for review (and reopens it if currently closed). Ignored when state is "closed".

base string

New base branch. Retargets the pull request and may update stack parentage when the new base is another change's head (or the default branch).

Response Fields

id string

Stable Origin pull request identifier.

number string

Repository-local pull request number encoded as a JSON string.

state string

Pull request state; open or closed. Merged pull requests are closed with merged set true.

draft boolean

Whether the pull request is a draft.

merged boolean

Whether the pull request has merged.

title string

Pull request title.

body string

Pull request description body.

head object

The source side of the change - what is being merged in.

head.ref string

The ref this side points at, as Origin records it.

head.sha string

Tip commit SHA of this side at the change's latest version.

base object

The target side of the change — what it merges into.

base.ref string

The ref this side points at, as Origin records it.

base.sha string

Tip commit SHA of this side at the change's latest version.

author object

Public actor that opened the pull request.

author.user object

User variant of the actor. Set when a user performed the action.

author.user.id string

Public identifier for the user.

author.user.email string

Email address of the user. Always set when the user variant is present.

author.app object

App variant of the actor. Set when an app performed the action.

author.app.id string

Public identifier for the app.

author.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

author.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

author.serviceAccount.id string

Public identifier for the service account.

createdAt string

RFC 3339 pull request creation timestamp.

updatedAt string

RFC 3339 timestamp for the latest pull request update.

closedAt string

RFC 3339 close timestamp; may appear on closed or merged pull requests.

mergedAt string

RFC 3339 merge timestamp; may appear on merged pull requests.

mergeCommitSha string

Merge commit SHA; may appear after merge.

additions integer

Added lines in the current pull request version.

deletions integer

Deleted lines in the current pull request version.

changedFiles integer

Changed file count in the current pull request version.

labels array

Labels currently assigned to the pull request, sorted by name. Empty when none are assigned.

labels[].id string

Public identifier for the label.

labels[].name string

Label name, unique within the repository. Names address the label in the write endpoints.

labels[].color string

Six-character hex color without a leading #.

labels[].description string

Label description. Absent when the label has none.

version object

Current numbered pull request version and its head/base SHAs.

version.number string

Monotonic pull request version number encoded as a JSON string.

version.headSha string

Head SHA captured by this pull request version.

version.baseSha string

Base SHA captured by this pull request version.

version.createdAt string

RFC 3339 timestamp for creation of this pull request version.

curl --request PATCH \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "title": "TITLE"}'

Response shape:

{  "id": "string",  "number": "string",  "state": "string",  "draft": false,  "merged": false,  "title": "string",  "body": "string",  "head": {    "ref": "string",    "sha": "string"  },  "base": {    "ref": "string",    "sha": "string"  },  "author": {    "user": {      "id": "string",      "email": "string"    }  },  "createdAt": "2026-01-01T00:00:00Z",  "updatedAt": "2026-01-01T00:00:00Z",  "closedAt": "2026-01-01T00:00:00Z",  "mergedAt": "2026-01-01T00:00:00Z",  "mergeCommitSha": "string",  "additions": 0,  "deletions": 0,  "changedFiles": 0,  "labels": [    {      "id": "string",      "name": "string",      "color": "string",      "description": "string"    }  ],  "version": {    "number": "string",    "headSha": "string",    "baseSha": "string",    "createdAt": "2026-01-01T00:00:00Z"  }}

List Pull Request Comments

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/comments

Lists every comment on a pull request in chronological order. Each comment includes its thread id so clients can group the flat response into threads.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

Query Parameters

pageSize integer

Maximum comments to return. Defaults to 30; maximum 100.

pageToken string

Opaque token from the preceding page.

Response Fields

comments array

Visible general and inline comments as one flat chronological list; group them by thread.id.

comments[].id string

Stable pull request comment identifier.

comments[].thread object

Thread reference used to group related comments.

comments[].thread.id string

Identifier used to group comments in one pull request discussion thread.

comments[].body string

Comment text.

comments[].author object

Public actor that authored the comment.

comments[].author.user object

User variant of the actor. Set when a user performed the action.

comments[].author.user.id string

Public identifier for the user.

comments[].author.user.email string

Email address of the user. Always set when the user variant is present.

comments[].author.app object

App variant of the actor. Set when an app performed the action.

comments[].author.app.id string

Public identifier for the app.

comments[].author.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

comments[].author.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

comments[].author.serviceAccount.id string

Public identifier for the service account.

comments[].createdAt string

RFC 3339 comment creation timestamp.

comments[].updatedAt string

RFC 3339 timestamp for the latest comment edit.

pullRequest object

Container PullRequestReference included alongside the comments page.

pullRequest.id string

Stable pull request identifier.

pullRequest.number string

Repository-local pull request number encoded as a JSON string.

pullRequest.repository object

Repository container reference for the pull request.

pullRequest.repository.id string

Repository identifier in a container reference.

pullRequest.repository.name string

Repository name in a container reference.

pullRequest.repository.owner object

Owner reference for the repository.

pullRequest.repository.owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

pullRequest.repository.owner.id string

Origin owner identifier.

pullRequest.repository.owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

nextPageToken string

Empty when there are no more comments.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/comments' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "comments": [    {      "id": "string",      "thread": {        "id": "string"      },      "body": "string",      "author": {        "user": {          "id": "string",          "email": "string"        }      },      "createdAt": "2026-01-01T00:00:00Z",      "updatedAt": "2026-01-01T00:00:00Z"    }  ],  "pullRequest": {    "id": "string",    "number": "string",    "repository": {      "id": "string",      "name": "string",      "owner": {        "slug": "string",        "id": "string",        "type": "team"      }    }  },  "nextPageToken": "string"}

Get Pull Request Comment

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/comments/{commentId}

Returns a single pull request comment by its stable Origin id. A comment outside the authorized repository, or a pending-review comment not visible to the caller, returns 404.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

commentId string Required

Response Fields

id string

Stable pull request comment identifier.

thread object

Thread reference used to group related comments.

thread.id string

Identifier used to group comments in one pull request discussion thread.

body string

Comment text.

author object

Public actor that authored the comment.

author.user object

User variant of the actor. Set when a user performed the action.

author.user.id string

Public identifier for the user.

author.user.email string

Email address of the user. Always set when the user variant is present.

author.app object

App variant of the actor. Set when an app performed the action.

author.app.id string

Public identifier for the app.

author.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

author.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

author.serviceAccount.id string

Public identifier for the service account.

createdAt string

RFC 3339 comment creation timestamp.

updatedAt string

RFC 3339 timestamp for the latest comment edit.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/comments/COMMENT_ID' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "id": "string",  "thread": {    "id": "string"  },  "body": "string",  "author": {    "user": {      "id": "string",      "email": "string"    }  },  "createdAt": "2026-01-01T00:00:00Z",  "updatedAt": "2026-01-01T00:00:00Z"}

Create Pull Request Comment

POST/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/comments

Creates a general-discussion comment or reply on an Origin pull request. Omitting thread_id starts a new thread; providing it replies to that thread. These are general-discussion comments, not diff-anchored review comments. Bodies longer than 65,536 characters are rejected with InvalidArgument (HTTP 400).

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

Request Body

body string Required

Comment text. Maximum length: 65,536 characters, counted as Unicode code points.

threadId string

Existing thread id to reply to. Omit to create a new general-discussion thread.

Response Fields

id string

Stable pull request comment identifier.

thread object

Thread reference used to group related comments.

thread.id string

Identifier used to group comments in one pull request discussion thread.

body string

Comment text.

author object

Public actor that authored the comment.

author.user object

User variant of the actor. Set when a user performed the action.

author.user.id string

Public identifier for the user.

author.user.email string

Email address of the user. Always set when the user variant is present.

author.app object

App variant of the actor. Set when an app performed the action.

author.app.id string

Public identifier for the app.

author.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

author.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

author.serviceAccount.id string

Public identifier for the service account.

createdAt string

RFC 3339 comment creation timestamp.

updatedAt string

RFC 3339 timestamp for the latest comment edit.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/comments' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "body": "BODY"}'

Response shape:

{  "id": "string",  "thread": {    "id": "string"  },  "body": "string",  "author": {    "user": {      "id": "string",      "email": "string"    }  },  "createdAt": "2026-01-01T00:00:00Z",  "updatedAt": "2026-01-01T00:00:00Z"}

Update Pull Request Comment

PATCH/v1/origin/repos/{ownerSlug}/{repoName}/pulls/comments/{commentId}

Updates a pull request comment by its stable Origin id.

Replaces the comment body. The comment must belong to the repository in the path, be visible to the caller, and have been authored by that caller. Cross-repository and hidden pending-review comments return 404; a visible comment owned by another actor returns 403. Bodies longer than 65,536 characters are rejected with InvalidArgument (HTTP 400).

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

commentId string Required

Request Body

body string Required

Replacement comment text. Maximum length: 65,536 characters, counted as Unicode code points.

Response Fields

id string

Stable pull request comment identifier.

thread object

Thread reference used to group related comments.

thread.id string

Identifier used to group comments in one pull request discussion thread.

body string

Comment text.

author object

Public actor that authored the comment.

author.user object

User variant of the actor. Set when a user performed the action.

author.user.id string

Public identifier for the user.

author.user.email string

Email address of the user. Always set when the user variant is present.

author.app object

App variant of the actor. Set when an app performed the action.

author.app.id string

Public identifier for the app.

author.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

author.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

author.serviceAccount.id string

Public identifier for the service account.

createdAt string

RFC 3339 comment creation timestamp.

updatedAt string

RFC 3339 timestamp for the latest comment edit.

curl --request PATCH \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/comments/COMMENT_ID' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "body": "BODY"}'

Response shape:

{  "id": "string",  "thread": {    "id": "string"  },  "body": "string",  "author": {    "user": {      "id": "string",      "email": "string"    }  },  "createdAt": "2026-01-01T00:00:00Z",  "updatedAt": "2026-01-01T00:00:00Z"}

List Pull Request Commits

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/commits

Lists the commits in a pull request.

Returns the pull request's commits as sparse Commit objects (no stats). Results default to 30 and are capped at 100, with at most 250 commits visible overall. A page token fixes the pull request version, page size, and commit cursor; pageSize must match the token on later requests, and a token that no longer matches the current head or base returns 400.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

Query Parameters

pageSize integer

Max commits to return. Defaults to 30 when unset or 0. Values above 100 are clamped to 100.

pageToken string

Opaque cursor from a previous response's next_page_token. Empty for the first page. The token is bound to the repository, pull request version, page size, and commit offset.

Response Fields

commits array

Sparse commits with no stats, with at most 250 commits visible overall.

commits[].sha string

Full commit SHA.

commits[].commit object

Git-object metadata nested separately from top-level repository relationships.

commits[].commit.author object

Git author identity recorded in the commit, not an Origin user object.

commits[].commit.author.name string

Name recorded in the Git author identity.

commits[].commit.author.email string

Email recorded in the Git author identity.

commits[].commit.author.date string

RFC 3339 date recorded in the Git author identity.

commits[].commit.committer object

Git committer identity recorded in the commit, not an Origin user object.

commits[].commit.committer.name string

Name recorded in the Git identity.

commits[].commit.committer.email string

Email recorded in the Git identity.

commits[].commit.committer.date string

ISO-8601 timestamp preserving the git signature's original timezone offset (e.g. "2014-11-07T22:01:45+01:00").

commits[].commit.message string

Commit message.

commits[].commit.tree object

Tree referenced by the commit.

commits[].commit.tree.sha string

SHA of the tree referenced by the commit.

commits[].parents array

Parent commit references, each containing a SHA.

commits[].parents[].sha string

Parent commit SHA.

nextPageToken string

Token fixes the pull request version, page size, and commit cursor; a token stale against the current head or base returns 400.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/commits' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "commits": [    {      "sha": "string",      "commit": {        "author": {          "name": "string",          "email": "string",          "date": "string"        },        "committer": {          "name": "string",          "email": "string",          "date": "string"        },        "message": "string",        "tree": {          "sha": "string"        }      },      "parents": [        {          "sha": "string"        }      ]    }  ],  "nextPageToken": "string"}

List Pull Request Files

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/files

Lists the files changed in a pull request.

Returns filename, status, line counts, patch, and optional previous filename. Results default to 30 files and are capped at 100. A page token fixes the pull request version, page size, and file cursor; pageSize must match the token on later requests, and a token that no longer matches the current head or base returns 400.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

Query Parameters

pageSize integer

Max changed files to return. Defaults to 30 when unset or 0. Values above 100 are clamped to 100.

pageToken string

Opaque cursor from a previous response's next_page_token. Empty for the first page. The token is bound to the repository, pull request version, page size, and changed-file cursor.

Response Fields

files array

Changed-file records for the current pull request version.

files[].filename string

Path of the changed pull request file.

files[].status string

Change status; added, removed, modified, renamed, or copied.

files[].additions integer

Added line count for the file.

files[].deletions integer

Deleted line count for the file.

files[].changes integer

Total changed line count for the file.

files[].patch string

Unified patch for the file.

files[].previousFilename string

Previous path when the file was renamed or copied.

nextPageToken string

Token fixes pull request version, page size, and file cursor; a token stale against the current head or base returns 400.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/files' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "files": [    {      "filename": "string",      "status": "string",      "additions": 0,      "deletions": 0,      "changes": 0,      "patch": "string",      "previousFilename": "string"    }  ],  "nextPageToken": "string"}

List Pull Request Labels

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/labels

Lists every label assigned to a pull request, ordered by name.

The response carries the full assigned list rather than a page of it, so this endpoint takes no pagination parameters. A pull request can have at most 100 labels. An unknown pull request returns 404.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

Response Fields

labels array

Every label currently assigned to the pull request, sorted by name.

labels[].id string

Public identifier for the label.

labels[].name string

Label name, unique within the repository. Names address the label in the write endpoints.

labels[].color string

Six-character hex color without a leading #.

labels[].description string

Label description. Absent when the label has none.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/labels' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "labels": [    {      "id": "string",      "name": "string",      "color": "string",      "description": "string"    }  ]}

Set Pull Request Labels

PUT/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/labels

Replaces every label assigned to a pull request with the labels you name.

An empty list removes every assigned label. The labels must already exist in the repository; an unknown name or an unknown pull request returns 404. A pull request can have at most 100 labels, so naming more than 100 returns FailedPrecondition (HTTP 400). The response lists the labels assigned after the replacement, ordered by name.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

Request Body

labels array

Label names to assign. Maximum 100. An empty list removes every assigned label. Duplicate names are ignored.

Response Fields

labels array

Labels assigned after the replacement, ordered by name. Each entry carries id, name, color, and description.

curl --request PUT \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/labels' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "labels": [    "LABEL_NAME"  ]}'

Response shape:

{  "labels": [    {      "id": "string",      "name": "string",      "color": "string",      "description": "string"    }  ]}

Add Pull Request Labels

POST/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/labels

Adds existing repository labels to a pull request.

Labels already assigned to the pull request stay assigned. The labels must already exist in the repository; an unknown name or an unknown pull request returns 404. The request must name between 1 and 100 labels, and a pull request can have at most 100 labels in total, so a request that would take it past that limit returns FailedPrecondition (HTTP 400). The response lists the labels you named, not the pull request's full set; read the full set with List Pull Request Labels.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

Request Body

labels array Required

Label names to add. Maximum 100. Duplicate names are ignored.

Response Fields

labels array

Labels named in the request. Each entry carries id, name, color, and description.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/labels' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "labels": [    "LABEL_NAME"  ]}'

Response shape:

{  "labels": [    {      "id": "string",      "name": "string",      "color": "string",      "description": "string"    }  ]}

Remove All Pull Request Labels

DELETE/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/labels

Removes every label from a pull request.

The request succeeds when the pull request has no labels. An unknown pull request returns 404. The response body is empty.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

Response Fields

Successful requests return no response body.

curl --request DELETE \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/labels' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response:

204 No Content

Remove Pull Request Label

DELETE/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/labels/{labelName}

Removes one label from a pull request.

A label that is not assigned to the pull request returns 404, as does an unknown pull request. The response lists the labels remaining on the pull request, ordered by name.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

labelName string Required

Name of the label to remove.

Response Fields

labels array

Labels remaining on the pull request, ordered by name. Each entry carries id, name, color, and description.

curl --request DELETE \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/labels/LABEL_NAME' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "labels": [    {      "id": "string",      "name": "string",      "color": "string",      "description": "string"    }  ]}

Merge Pull Request

POST/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/merge

Merges a pull request into its base.

For a stacked pull request, merges the entire root-to-target prefix ending at this pull number. not only this pull. Supported only on native Origin repositories; mirrored repositories are rejected.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

Pull number to merge. When this pull is stacked, the merge lands every pull from the stack root through this number.

Request Body

expectedHeadSha string

Guard against merging a head your app has not seen: the full commit SHA (40 or 64 hexadecimal characters) expected to be the pull request's current head. When the head has moved, the merge is rejected with ABORTED (HTTP 409 Conflict) and nothing merges. Values that are not a full commit SHA are rejected with InvalidArgument (HTTP 400). Omit to merge whatever the current head is. Not evaluated when the pull request is already merged, which returns idempotent success.

Response Fields

mergeCommitSha string

SHA of the merge commit written to the base.

mergedPullNumbers array

JSON-string pull request numbers merged from stack root through the target.

pullRequest object

Target PullRequest after merge; the declared response type is the full resource even though the example is abbreviated.

pullRequest.id string

Stable Origin pull request identifier.

pullRequest.number string

Repository-local pull request number encoded as a JSON string.

pullRequest.state string

Pull request state; open or closed. Merged pull requests are closed with merged set true.

pullRequest.draft boolean

Whether the pull request is a draft.

pullRequest.merged boolean

Whether the pull request has merged.

pullRequest.title string

Pull request title.

pullRequest.body string

Pull request description body.

pullRequest.head object

The source side of the change - what is being merged in.

pullRequest.head.ref string

The ref this side points at, as Origin records it.

pullRequest.head.sha string

Tip commit SHA of this side at the change's latest version.

pullRequest.base object

The target side of the change — what it merges into.

pullRequest.base.ref string

The ref this side points at, as Origin records it.

pullRequest.base.sha string

Tip commit SHA of this side at the change's latest version.

pullRequest.author object

Public actor that opened the pull request.

pullRequest.author.user object

User variant of the actor. Set when a user performed the action.

pullRequest.author.user.id string

Public identifier for the user.

pullRequest.author.user.email string

Email address of the user. Always set when the user variant is present.

pullRequest.author.app object

App variant of the actor. Set when an app performed the action.

pullRequest.author.app.id string

Public identifier for the app.

pullRequest.author.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

pullRequest.author.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

pullRequest.author.serviceAccount.id string

Public identifier for the service account.

pullRequest.createdAt string

RFC 3339 pull request creation timestamp.

pullRequest.updatedAt string

RFC 3339 timestamp for the latest pull request update.

pullRequest.closedAt string

RFC 3339 close timestamp; may appear on closed or merged pull requests.

pullRequest.mergedAt string

RFC 3339 merge timestamp; may appear on merged pull requests.

pullRequest.mergeCommitSha string

Merge commit SHA; may appear after merge.

pullRequest.additions integer

Added lines in the current pull request version.

pullRequest.deletions integer

Deleted lines in the current pull request version.

pullRequest.changedFiles integer

Changed file count in the current pull request version.

pullRequest.labels array

Labels currently assigned to the pull request, sorted by name. Empty when none are assigned.

pullRequest.labels[].id string

Public identifier for the label.

pullRequest.labels[].name string

Label name, unique within the repository. Names address the label in the write endpoints.

pullRequest.labels[].color string

Six-character hex color without a leading #.

pullRequest.labels[].description string

Label description. Absent when the label has none.

pullRequest.version object

Current numbered pull request version and its head/base SHAs.

pullRequest.version.number string

Monotonic pull request version number encoded as a JSON string.

pullRequest.version.headSha string

Head SHA captured by this pull request version.

pullRequest.version.baseSha string

Base SHA captured by this pull request version.

pullRequest.version.createdAt string

RFC 3339 timestamp for creation of this pull request version.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/merge' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{    "expectedHeadSha": "EXPECTED_HEAD_SHA"  }'

Response shape:

{  "mergeCommitSha": "string",  "mergedPullNumbers": [    "string"  ],  "pullRequest": {    "id": "string",    "number": "string",    "state": "string",    "draft": false,    "merged": false,    "title": "string",    "body": "string",    "head": {      "ref": "string",      "sha": "string"    },    "base": {      "ref": "string",      "sha": "string"    },    "author": {      "user": {        "id": "string",        "email": "string"      }    },    "createdAt": "2026-01-01T00:00:00Z",    "updatedAt": "2026-01-01T00:00:00Z",    "closedAt": "2026-01-01T00:00:00Z",    "mergedAt": "2026-01-01T00:00:00Z",    "mergeCommitSha": "string",    "additions": 0,    "deletions": 0,    "changedFiles": 0,    "labels": [      {        "id": "string",        "name": "string",        "color": "string",        "description": "string"      }    ],    "version": {      "number": "string",      "headSha": "string",      "baseSha": "string",      "createdAt": "2026-01-01T00:00:00Z"    }  }}

List Pull Request Reviews

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/reviews

Lists submitted reviews on a pull request, ordered by submitted_at ascending. Pending reviews are omitted.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

Query Parameters

pageSize integer

Maximum reviews to return. Defaults to 30; maximum 100.

pageToken string

Opaque token from the preceding page.

Response Fields

reviews array

Submitted reviews ordered by submittedAt ascending; unsubmitted draft reviews are omitted.

reviews[].id string

Stable review identifier.

reviews[].author object

Public actor that authored the review.

reviews[].author.user object

User variant of the actor. Set when a user performed the action.

reviews[].author.user.id string

Public identifier for the user.

reviews[].author.user.email string

Email address of the user. Always set when the user variant is present.

reviews[].author.app object

App variant of the actor. Set when an app performed the action.

reviews[].author.app.id string

Public identifier for the app.

reviews[].author.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

reviews[].author.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

reviews[].author.serviceAccount.id string

Public identifier for the service account.

reviews[].verdict string

Review verdict; approve, request_changes, or comment.

reviews[].body string

Review summary text.

reviews[].submittedAt string

RFC 3339 submission timestamp; absent for an unsubmitted draft review.

reviews[].pullRequestVersion object

Pull request version to which the review applies.

reviews[].pullRequestVersion.number string

Monotonic pull request version number encoded as a JSON string.

reviews[].pullRequestVersion.headSha string

Head SHA captured by this pull request version.

reviews[].pullRequestVersion.baseSha string

Base SHA captured by this pull request version.

reviews[].pullRequestVersion.createdAt string

RFC 3339 timestamp for creation of this pull request version.

reviews[].dismissal object

Present after a review is dismissed; dismissed reviews remain visible in listings.

reviews[].dismissal.dismissedBy object

Public actor that dismissed the review when exposed.

reviews[].dismissal.dismissedBy.user object

User variant of the actor. Set when a user performed the action.

reviews[].dismissal.dismissedBy.user.id string

Public identifier for the user.

reviews[].dismissal.dismissedBy.user.email string

Email address of the user. Always set when the user variant is present.

reviews[].dismissal.dismissedBy.app object

App variant of the actor. Set when an app performed the action.

reviews[].dismissal.dismissedBy.app.id string

Public identifier for the app.

reviews[].dismissal.dismissedBy.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

reviews[].dismissal.dismissedBy.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

reviews[].dismissal.dismissedBy.serviceAccount.id string

Public identifier for the service account.

reviews[].dismissal.dismissedAt string

RFC 3339 dismissal timestamp.

reviews[].dismissal.message string

Dismissal reason; automatic supersession uses a server-generated message.

pullRequest object

Container PullRequestReference included alongside the reviews page.

pullRequest.id string

Stable pull request identifier.

pullRequest.number string

Repository-local pull request number encoded as a JSON string.

pullRequest.repository object

Repository container reference for the pull request.

pullRequest.repository.id string

Repository identifier in a container reference.

pullRequest.repository.name string

Repository name in a container reference.

pullRequest.repository.owner object

Owner reference for the repository.

pullRequest.repository.owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

pullRequest.repository.owner.id string

Origin owner identifier.

pullRequest.repository.owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

nextPageToken string

Opaque token for the next page; empty when there are no more reviews.

curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/reviews' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response shape:

{  "reviews": [    {      "id": "string",      "author": {        "user": {          "id": "string",          "email": "string"        }      },      "verdict": "approve",      "body": "string",      "submittedAt": "2026-01-01T00:00:00Z",      "pullRequestVersion": {        "number": "string",        "headSha": "string",        "baseSha": "string",        "createdAt": "2026-01-01T00:00:00Z"      },      "dismissal": {        "dismissedBy": {          "user": {            "id": "string",            "email": "string"          }        },        "dismissedAt": "2026-01-01T00:00:00Z",        "message": "string"      }    }  ],  "pullRequest": {    "id": "string",    "number": "string",    "repository": {      "id": "string",      "name": "string",      "owner": {        "slug": "string",        "id": "string",        "type": "team"      }    }  },  "nextPageToken": "string"}

Create Pull Request Review

POST/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/reviews

Creates and submits a review on a pull request.

The review is submitted immediately. A new approve or request_changes review supersedes the caller's prior live decision review on the same pull request, which is dismissed. Pull request authors cannot approve their own pull request. Fails with FAILED_PRECONDITION while the caller has an unsubmitted draft review on the pull request.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

Request Body

verdict string Required

The review decision. Allowed values: PULL_REQUEST_REVIEW_VERDICT_UNSPECIFIED, approve, request_changes, comment.

body string

Free-text review summary. May be empty.

versionNumber string

Pull request version number the review applies to (see PullRequestVersion.number). Omit to review the latest version at call time.

Response Fields

id string

Stable review identifier.

author object

Public actor that authored the review.

author.user object

User variant of the actor. Set when a user performed the action.

author.user.id string

Public identifier for the user.

author.user.email string

Email address of the user. Always set when the user variant is present.

author.app object

App variant of the actor. Set when an app performed the action.

author.app.id string

Public identifier for the app.

author.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

author.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

author.serviceAccount.id string

Public identifier for the service account.

verdict string

Review verdict; approve, request_changes, or comment.

body string

Review summary text.

submittedAt string

RFC 3339 submission timestamp; absent for an unsubmitted draft review.

pullRequestVersion object

Pull request version to which the review applies.

pullRequestVersion.number string

Monotonic pull request version number encoded as a JSON string.

pullRequestVersion.headSha string

Head SHA captured by this pull request version.

pullRequestVersion.baseSha string

Base SHA captured by this pull request version.

pullRequestVersion.createdAt string

RFC 3339 timestamp for creation of this pull request version.

dismissal object

Present after a review is dismissed; dismissed reviews remain visible in listings.

dismissal.dismissedBy object

Public actor that dismissed the review when exposed.

dismissal.dismissedBy.user object

User variant of the actor. Set when a user performed the action.

dismissal.dismissedBy.user.id string

Public identifier for the user.

dismissal.dismissedBy.user.email string

Email address of the user. Always set when the user variant is present.

dismissal.dismissedBy.app object

App variant of the actor. Set when an app performed the action.

dismissal.dismissedBy.app.id string

Public identifier for the app.

dismissal.dismissedBy.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

dismissal.dismissedBy.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

dismissal.dismissedBy.serviceAccount.id string

Public identifier for the service account.

dismissal.dismissedAt string

RFC 3339 dismissal timestamp.

dismissal.message string

Dismissal reason; automatic supersession uses a server-generated message.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/reviews' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "verdict": "approve"}'

Response shape:

{  "id": "string",  "author": {    "user": {      "id": "string",      "email": "string"    }  },  "verdict": "approve",  "body": "string",  "submittedAt": "2026-01-01T00:00:00Z",  "pullRequestVersion": {    "number": "string",    "headSha": "string",    "baseSha": "string",    "createdAt": "2026-01-01T00:00:00Z"  },  "dismissal": {    "dismissedBy": {      "user": {        "id": "string",        "email": "string"      }    },    "dismissedAt": "2026-01-01T00:00:00Z",    "message": "string"  }}

Update Pull Request Review

PATCH/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/reviews/{reviewId}

Updates the body of a review. Only the review author can update it; other callers receive PERMISSION_DENIED. A review that does not belong to the named pull request returns NOT_FOUND.

Unsubmitted draft reviews can be updated too; a draft's response has no submitted_at.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

reviewId string Required

Request Body

body string Required

Replacement review summary text; replaces the prior body in full. Must contain a non-whitespace character; INVALID_ARGUMENT otherwise.

Response Fields

id string

Stable review identifier.

author object

Public actor that authored the review.

author.user object

User variant of the actor. Set when a user performed the action.

author.user.id string

Public identifier for the user.

author.user.email string

Email address of the user. Always set when the user variant is present.

author.app object

App variant of the actor. Set when an app performed the action.

author.app.id string

Public identifier for the app.

author.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

author.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

author.serviceAccount.id string

Public identifier for the service account.

verdict string

Review verdict; approve, request_changes, or comment.

body string

Review summary text.

submittedAt string

RFC 3339 submission timestamp; absent for an unsubmitted draft review.

pullRequestVersion object

Pull request version to which the review applies.

pullRequestVersion.number string

Monotonic pull request version number encoded as a JSON string.

pullRequestVersion.headSha string

Head SHA captured by this pull request version.

pullRequestVersion.baseSha string

Base SHA captured by this pull request version.

pullRequestVersion.createdAt string

RFC 3339 timestamp for creation of this pull request version.

dismissal object

Present after a review is dismissed; dismissed reviews remain visible in listings.

dismissal.dismissedBy object

Public actor that dismissed the review when exposed.

dismissal.dismissedBy.user object

User variant of the actor. Set when a user performed the action.

dismissal.dismissedBy.user.id string

Public identifier for the user.

dismissal.dismissedBy.user.email string

Email address of the user. Always set when the user variant is present.

dismissal.dismissedBy.app object

App variant of the actor. Set when an app performed the action.

dismissal.dismissedBy.app.id string

Public identifier for the app.

dismissal.dismissedBy.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

dismissal.dismissedBy.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

dismissal.dismissedBy.serviceAccount.id string

Public identifier for the service account.

dismissal.dismissedAt string

RFC 3339 dismissal timestamp.

dismissal.message string

Dismissal reason; automatic supersession uses a server-generated message.

curl --request PATCH \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/reviews/REVIEW_ID' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "body": "BODY"}'

Response shape:

{  "id": "string",  "author": {    "user": {      "id": "string",      "email": "string"    }  },  "verdict": "approve",  "body": "string",  "submittedAt": "2026-01-01T00:00:00Z",  "pullRequestVersion": {    "number": "string",    "headSha": "string",    "baseSha": "string",    "createdAt": "2026-01-01T00:00:00Z"  },  "dismissal": {    "dismissedBy": {      "user": {        "id": "string",        "email": "string"      }    },    "dismissedAt": "2026-01-01T00:00:00Z",    "message": "string"  }}

Dismiss Pull Request Review

PUT/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/reviews/{reviewId}/dismissals

Dismisses a submitted review so its verdict no longer counts toward the pull request's review state. The review itself is retained and keeps appearing in ListPullRequestReviews, with dismissal set.

Dismissing does not require having authored the review; write permission on the repository's pull request reviews is sufficient.

Only approve and request_changes reviews can be dismissed, and only once: a comment review, an unsubmitted draft review, or an already-dismissed review returns FAILED_PRECONDITION, and repeating the call leaves the first dismissal in place. A review that does not belong to the named pull request returns NOT_FOUND.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

pullNumber string Required

reviewId string Required

Stable Origin review identifier, as returned by ListPullRequestReviews.

Request Body

message string Required

Reason recorded with the dismissal. Must contain a non-whitespace character; INVALID_ARGUMENT otherwise.

Response Fields

id string

Stable review identifier.

author object

Public actor that authored the review.

author.user object

User variant of the actor. Set when a user performed the action.

author.user.id string

Public identifier for the user.

author.user.email string

Email address of the user. Always set when the user variant is present.

author.app object

App variant of the actor. Set when an app performed the action.

author.app.id string

Public identifier for the app.

author.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

author.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

author.serviceAccount.id string

Public identifier for the service account.

verdict string

Review verdict; approve, request_changes, or comment.

body string

Review summary text.

submittedAt string

RFC 3339 submission timestamp; absent for an unsubmitted draft review.

pullRequestVersion object

Pull request version to which the review applies.

pullRequestVersion.number string

Monotonic pull request version number encoded as a JSON string.

pullRequestVersion.headSha string

Head SHA captured by this pull request version.

pullRequestVersion.baseSha string

Base SHA captured by this pull request version.

pullRequestVersion.createdAt string

RFC 3339 timestamp for creation of this pull request version.

dismissal object

Present after a review is dismissed; dismissed reviews remain visible in listings.

dismissal.dismissedBy object

Public actor that dismissed the review when exposed.

dismissal.dismissedBy.user object

User variant of the actor. Set when a user performed the action.

dismissal.dismissedBy.user.id string

Public identifier for the user.

dismissal.dismissedBy.user.email string

Email address of the user. Always set when the user variant is present.

dismissal.dismissedBy.app object

App variant of the actor. Set when an app performed the action.

dismissal.dismissedBy.app.id string

Public identifier for the app.

dismissal.dismissedBy.app.slug string

URL-friendly name of the app. Always set when the app variant is present.

dismissal.dismissedBy.serviceAccount object

Service account variant of the actor. Set when a service account performed the action.

dismissal.dismissedBy.serviceAccount.id string

Public identifier for the service account.

dismissal.dismissedAt string

RFC 3339 dismissal timestamp.

dismissal.message string

Dismissal reason; automatic supersession uses a server-generated message.

curl --request PUT \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/reviews/REVIEW_ID/dismissals' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "message": "MESSAGE"}'

Response shape:

{  "id": "string",  "author": {    "user": {      "id": "string",      "email": "string"    }  },  "verdict": "approve",  "body": "string",  "submittedAt": "2026-01-01T00:00:00Z",  "pullRequestVersion": {    "number": "string",    "headSha": "string",    "baseSha": "string",    "createdAt": "2026-01-01T00:00:00Z"  },  "dismissal": {    "dismissedBy": {      "user": {        "id": "string",        "email": "string"      }    },    "dismissedAt": "2026-01-01T00:00:00Z",    "message": "string"  }}

Rulesets

List Rulesets

GET/v1/origin/repos/{ownerSlug}/{repoName}/rulesets

Lists every ruleset configured on a repository.

Rulesets per repository are bounded configuration, so the full set comes back in one response and this endpoint does not paginate. repository is hoisted once and describes the repository shared by every ruleset in the response.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

Response Fields

rulesets array

Rulesets configured on the repository.

rulesets[].id string

Stable Origin ruleset ID.

rulesets[].name string

Ruleset name.

rulesets[].description string

Ruleset description.

rulesets[].enforcement string

How Origin enforces the ruleset. Allowed values: active, evaluate, disabled.

rulesets[].kind string

The operation the ruleset protects. Allowed values: merge_branch, push_branch, push_tag, push_repository.

rulesets[].includedRefNames array

Ref name patterns this ruleset includes. Supports globs and the tokens ~ALL and ~DEFAULT_BRANCH.

rulesets[].excludedRefNames array

Ref name patterns this ruleset excludes. Same pattern language as rulesets[].includedRefNames.

rulesets[].rules array

Protection rules in this ruleset.

rulesets[].rules[].id string

Stable Origin ID for this rule.

rulesets[].rules[].ruleType string

Rule type, for example pull_request, require_status_checks, require_branch_up_to_date, deletion, or non_fast_forward.

rulesets[].rules[].parameters object

Type-specific parameters as a JSON object. The shape depends on rulesets[].rules[].ruleType.

rulesets[].bypassActors array

Principals that can bypass this ruleset. A bypass actor whose stored identity cannot be read is omitted from the response.

rulesets[].bypassActors[].id string

Stable Origin ID for this bypass actor.

rulesets[].bypassActors[].bypassMode string

When the bypass applies. Allowed values: always, pull_request_only.

rulesets[].bypassActors[].user object

A user principal. Exactly one of user, team, app, or originRole is present.

rulesets[].bypassActors[].user.id string

Numeric Cursor user ID encoded as a decimal string.

rulesets[].bypassActors[].team object

A team principal.

rulesets[].bypassActors[].team.organizationPublicId string

Immutable organization public ID.

rulesets[].bypassActors[].team.groupPublicId string

Immutable group public ID.

rulesets[].bypassActors[].app object

An app principal.

rulesets[].bypassActors[].app.id string

App ID, prefixed app_.

rulesets[].bypassActors[].originRole object

A principal holding an Origin role.

rulesets[].bypassActors[].originRole.role string

Allowed values: namespace_admin, repository_admin, repository_write.

repository object

Repository shared by every ruleset in this response.

repository.id string

Repository identifier in a container reference.

repository.name string

Repository name in a container reference.

repository.owner object

Owner reference for the repository.

repository.owner.slug string

URL-facing owner slug used with the owner ID to identify the repository owner.

repository.owner.id string

Origin owner identifier.

repository.owner.type string

Owner namespace type. Output-only. Allowed values: team, user. Omitted when unknown.

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

Response shape:

{  "rulesets": [    {      "id": "string",      "name": "string",      "description": "string",      "enforcement": "active",      "kind": "merge_branch",      "includedRefNames": [        "string"      ],      "excludedRefNames": [        "string"      ],      "rules": [        {          "id": "string",          "ruleType": "string",          "parameters": {}        }      ],      "bypassActors": [        {          "id": "string",          "bypassMode": "always",          "user": {            "id": "string"          }        }      ]    }  ],  "repository": {    "id": "string",    "name": "string",    "owner": {      "slug": "string",      "id": "string",      "type": "team"    }  }}

Create Ruleset

POST/v1/origin/repos/{ownerSlug}/{repoName}/rulesets

Creates a repository ruleset.

The response carries the stored ruleset, including the IDs Origin assigns to each rule and bypass actor. An empty name is rejected with InvalidArgument (HTTP 400).

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

Request Body

name string Required

Ruleset name.

description string

Ruleset description.

enforcement string Required

How Origin enforces the ruleset. Allowed values: active, evaluate, disabled.

kind string Required

The operation the ruleset protects. Allowed values: merge_branch, push_branch, push_tag, push_repository.

includedRefNames array

Ref name patterns this ruleset includes. Supports globs and the tokens ~ALL and ~DEFAULT_BRANCH. Values above 64 entries are rejected with InvalidArgument (HTTP 400).

excludedRefNames array

Ref name patterns this ruleset excludes. Same pattern language and 64-entry cap as includedRefNames.

rules array

Protection rules to store. Each entry carries ruleType and optional parameters; Origin assigns each rule's id. Values above 20 entries are rejected with InvalidArgument (HTTP 400).

bypassActors array

Bypass principals to store. Each entry carries bypassMode and exactly one of user, team, app, or originRole; Origin assigns each actor's id. Values above 15 entries are rejected with InvalidArgument (HTTP 400).

Response Fields

id string

Stable Origin ruleset ID.

name string

Ruleset name.

description string

Ruleset description.

enforcement string

How Origin enforces the ruleset. Allowed values: active, evaluate, disabled.

kind string

The operation the ruleset protects. Allowed values: merge_branch, push_branch, push_tag, push_repository.

includedRefNames array

Ref name patterns this ruleset includes. Supports globs and the tokens ~ALL and ~DEFAULT_BRANCH.

excludedRefNames array

Ref name patterns this ruleset excludes. Same pattern language as includedRefNames.

rules array

Protection rules in this ruleset.

rules[].id string

Stable Origin ID for this rule.

rules[].ruleType string

Rule type, for example pull_request, require_status_checks, require_branch_up_to_date, deletion, or non_fast_forward.

rules[].parameters object

Type-specific parameters as a JSON object. The shape depends on rules[].ruleType.

bypassActors array

Principals that can bypass this ruleset. A bypass actor whose stored identity cannot be read is omitted from the response.

bypassActors[].id string

Stable Origin ID for this bypass actor.

bypassActors[].bypassMode string

When the bypass applies. Allowed values: always, pull_request_only.

bypassActors[].user object

A user principal. Exactly one of user, team, app, or originRole is present.

bypassActors[].user.id string

Numeric Cursor user ID encoded as a decimal string.

bypassActors[].team object

A team principal.

bypassActors[].team.organizationPublicId string

Immutable organization public ID.

bypassActors[].team.groupPublicId string

Immutable group public ID.

bypassActors[].app object

An app principal.

bypassActors[].app.id string

App ID, prefixed app_.

bypassActors[].originRole object

A principal holding an Origin role.

bypassActors[].originRole.role string

Allowed values: namespace_admin, repository_admin, repository_write.

curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/rulesets' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "name": "RULESET_NAME",  "description": "RULESET_DESCRIPTION",  "enforcement": "active",  "kind": "merge_branch",  "includedRefNames": [    "~DEFAULT_BRANCH"  ],  "excludedRefNames": [],  "rules": [    {      "ruleType": "pull_request",      "parameters": {}    }  ],  "bypassActors": [    {      "bypassMode": "always",      "app": {        "id": "APP_ID"      }    }  ]}'

Response shape:

{  "id": "string",  "name": "string",  "description": "string",  "enforcement": "active",  "kind": "merge_branch",  "includedRefNames": [    "string"  ],  "excludedRefNames": [    "string"  ],  "rules": [    {      "id": "string",      "ruleType": "string",      "parameters": {}    }  ],  "bypassActors": [    {      "id": "string",      "bypassMode": "always",      "user": {        "id": "string"      }    }  ]}

Get Ruleset

GET/v1/origin/repos/{ownerSlug}/{repoName}/rulesets/{rulesetId}

Returns a single repository ruleset by its stable Origin ID.

An unknown repository and an unknown ruleset both return 404; the message distinguishes them.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

rulesetId string Required

Stable Origin ruleset ID.

Response Fields

id string

Stable Origin ruleset ID.

name string

Ruleset name.

description string

Ruleset description.

enforcement string

How Origin enforces the ruleset. Allowed values: active, evaluate, disabled.

kind string

The operation the ruleset protects. Allowed values: merge_branch, push_branch, push_tag, push_repository.

includedRefNames array

Ref name patterns this ruleset includes. Supports globs and the tokens ~ALL and ~DEFAULT_BRANCH.

excludedRefNames array

Ref name patterns this ruleset excludes. Same pattern language as includedRefNames.

rules array

Protection rules in this ruleset.

rules[].id string

Stable Origin ID for this rule.

rules[].ruleType string

Rule type, for example pull_request, require_status_checks, require_branch_up_to_date, deletion, or non_fast_forward.

rules[].parameters object

Type-specific parameters as a JSON object. The shape depends on rules[].ruleType.

bypassActors array

Principals that can bypass this ruleset. A bypass actor whose stored identity cannot be read is omitted from the response.

bypassActors[].id string

Stable Origin ID for this bypass actor.

bypassActors[].bypassMode string

When the bypass applies. Allowed values: always, pull_request_only.

bypassActors[].user object

A user principal. Exactly one of user, team, app, or originRole is present.

bypassActors[].user.id string

Numeric Cursor user ID encoded as a decimal string.

bypassActors[].team object

A team principal.

bypassActors[].team.organizationPublicId string

Immutable organization public ID.

bypassActors[].team.groupPublicId string

Immutable group public ID.

bypassActors[].app object

An app principal.

bypassActors[].app.id string

App ID, prefixed app_.

bypassActors[].originRole object

A principal holding an Origin role.

bypassActors[].originRole.role string

Allowed values: namespace_admin, repository_admin, repository_write.

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

Response shape:

{  "id": "string",  "name": "string",  "description": "string",  "enforcement": "active",  "kind": "merge_branch",  "includedRefNames": [    "string"  ],  "excludedRefNames": [    "string"  ],  "rules": [    {      "id": "string",      "ruleType": "string",      "parameters": {}    }  ],  "bypassActors": [    {      "id": "string",      "bypassMode": "always",      "user": {        "id": "string"      }    }  ]}

Update Ruleset

PUT/v1/origin/repos/{ownerSlug}/{repoName}/rulesets/{rulesetId}

Updates an existing repository ruleset.

The request replaces the whole ruleset configuration. rules and bypassActors are replaced in full rather than merged, and Origin assigns new IDs to the stored entries, so send every rule and bypass actor you want to keep.

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

rulesetId string Required

Stable Origin ruleset ID.

Request Body

name string Required

Ruleset name.

description string

Ruleset description.

enforcement string Required

How Origin enforces the ruleset. Allowed values: active, evaluate, disabled.

kind string Required

The operation the ruleset protects. Allowed values: merge_branch, push_branch, push_tag, push_repository.

includedRefNames array

Ref name patterns this ruleset includes. Supports globs and the tokens ~ALL and ~DEFAULT_BRANCH. Values above 64 entries are rejected with InvalidArgument (HTTP 400).

excludedRefNames array

Ref name patterns this ruleset excludes. Same pattern language and 64-entry cap as includedRefNames.

rules array

Protection rules to store. Each entry carries ruleType and optional parameters; Origin assigns each rule's id. Values above 20 entries are rejected with InvalidArgument (HTTP 400).

bypassActors array

Response Fields

id string

Stable Origin ruleset ID.

name string

Ruleset name.

description string

Ruleset description.

enforcement string

How Origin enforces the ruleset. Allowed values: active, evaluate, disabled.

kind string

The operation the ruleset protects. Allowed values: merge_branch, push_branch, push_tag, push_repository.

includedRefNames array

Ref name patterns this ruleset includes. Supports globs and the tokens ~ALL and ~DEFAULT_BRANCH.

excludedRefNames array

Ref name patterns this ruleset excludes. Same pattern language as includedRefNames.

rules array

Protection rules in this ruleset.

rules[].id string

Stable Origin ID for this rule.

rules[].ruleType string

Rule type, for example pull_request, require_status_checks, require_branch_up_to_date, deletion, or non_fast_forward.

rules[].parameters object

Type-specific parameters as a JSON object. The shape depends on rules[].ruleType.

bypassActors array

Principals that can bypass this ruleset. A bypass actor whose stored identity cannot be read is omitted from the response.

bypassActors[].id string

Stable Origin ID for this bypass actor.

bypassActors[].bypassMode string

When the bypass applies. Allowed values: always, pull_request_only.

bypassActors[].user object

A user principal. Exactly one of user, team, app, or originRole is present.

bypassActors[].user.id string

Numeric Cursor user ID encoded as a decimal string.

bypassActors[].team object

A team principal.

bypassActors[].team.organizationPublicId string

Immutable organization public ID.

bypassActors[].team.groupPublicId string

Immutable group public ID.

bypassActors[].app object

An app principal.

bypassActors[].app.id string

App ID, prefixed app_.

bypassActors[].originRole object

A principal holding an Origin role.

bypassActors[].originRole.role string

Allowed values: namespace_admin, repository_admin, repository_write.

curl --request PUT \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/rulesets/RULESET_ID' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "name": "RULESET_NAME",  "description": "RULESET_DESCRIPTION",  "enforcement": "active",  "kind": "merge_branch",  "includedRefNames": [    "~DEFAULT_BRANCH"  ],  "excludedRefNames": [],  "rules": [    {      "ruleType": "pull_request",      "parameters": {}    }  ],  "bypassActors": [    {      "bypassMode": "always",      "app": {        "id": "APP_ID"      }    }  ]}'

Response shape:

{  "id": "string",  "name": "string",  "description": "string",  "enforcement": "active",  "kind": "merge_branch",  "includedRefNames": [    "string"  ],  "excludedRefNames": [    "string"  ],  "rules": [    {      "id": "string",      "ruleType": "string",      "parameters": {}    }  ],  "bypassActors": [    {      "id": "string",      "bypassMode": "always",      "user": {        "id": "string"      }    }  ]}

Delete Ruleset

DELETE/v1/origin/repos/{ownerSlug}/{repoName}/rulesets/{rulesetId}

Deletes a repository ruleset by its stable Origin ID. The response body is empty.

An unknown repository and an unknown ruleset both return 404; the message distinguishes them. A ruleset stored on a different repository reads as an unknown ruleset. An empty rulesetId returns InvalidArgument (HTTP 400).

Path Parameters

ownerSlug string Required

Owning entity's unique slug.

repoName string Required

Repo name, unique to the owner entity.

rulesetId string Required

Stable Origin ruleset ID.

Response Fields

Successful requests return no response body.

curl --request DELETE \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/rulesets/RULESET_ID' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response:

204 No Content

Command Palette

API Overview

Cloud Agents API

Admin API

Analytics API

AI Code Tracking API

Origin API

Origin API