Get Origin Pull Request Mergeability via the API

Preview whether a pull request can merge with GET https://api.cursor.com/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/mergeability. Official reference: Origin API → Get Pull Request Mergeability (OpenAPI OriginService_GetPullRequestMergeability). Changelog: September 15, 2026 (endpoint added; preview; expectedHeadSha; stack evaluation).

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

This operation is published in preview (x-cursor-visibility: PREVIEW in the OpenAPI specification). Decode responses with unknown fields and unknown enum values tolerated. Treat an unrecognized verdict as blocked. Pull request number is a JSON string (protobuf 64-bit encoding).

Cost: 10 points against the principal budget.

Path parameters

Param	Required	Meaning
ownerSlug	yes	Owning entity's unique slug
repoName	yes	Repo name, unique to the owner
pullNumber	yes	Pull request number within the repository (string on the wire)

Query parameters

Param	Required	Meaning
expectedHeadSha	no	Full commit SHA (40- or 64-character hex) expected as the current head. When set and the evaluated head differs, the request returns ABORTED (HTTP 409) instead of a verdict. Values that are not a full commit SHA return INVALID_ARGUMENT

A mirrored repository, or a stack of more than 200 pull requests (merged ancestors included), returns FailedPrecondition (HTTP 400). A missing or unreachable pull returns 404. A 404 never distinguishes a missing pull from one your installation cannot reach.

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

With a head guard:

curl --request GET \
  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/17/mergeability?expectedHeadSha=9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4' \
  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

Response

200 returns a PullRequestMergeability object. verdict is "mergeable" or "blocked". For a stacked pull, the verdict covers every pull from the stack root through this one; evaluatedPullRequests lists them stack-root first and ends with this pull (already-merged ancestors are omitted). blockers is empty when verdict is "mergeable"; each blocker carries kind, a human-readable message, and the pullRequest it belongs to.

{
  "pullRequest": {
    "id": "pr_01k2ja2000e0080000000000d4",
    "number": "17",
    "repository": {
      "id": "repo_01k2ja2000e0080000000000a1",
      "name": "launch-control",
      "owner": {
        "slug": "acme",
        "id": "ns_01k2ja2000e0080000000000b2"
      }
    }
  },
  "verdict": "blocked",
  "blockers": [
    {
      "pullRequest": {
        "id": "pr_01k2ja2000e0080000000000d4",
        "number": "17",
        "repository": {
          "id": "repo_01k2ja2000e0080000000000a1",
          "name": "launch-control",
          "owner": {
            "slug": "acme",
            "id": "ns_01k2ja2000e0080000000000b2"
          }
        }
      },
      "kind": "required_approvals",
      "message": "Approving review count is 0; 1 required. Request reviews and wait for the required approvals.",
      "requiredApprovals": {
        "requiredCount": 1,
        "approvedCount": 0
      }
    }
  ],
  "evaluatedPullRequests": [
    {
      "id": "pr_01k2ja2000e0080000000000d4",
      "number": "17",
      "repository": {
        "id": "repo_01k2ja2000e0080000000000a1",
        "name": "launch-control",
        "owner": {
          "slug": "acme",
          "id": "ns_01k2ja2000e0080000000000b2"
        }
      }
    }
  ],
  "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",
  "baseRef": "main",
  "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",
  "evaluatedAt": "2026-08-02T14:45:00Z"
}

headSha, baseRef, baseSha, and evaluatedAt describe the evaluation snapshot. Re-query after the head or base moves. New blocker kind values appear over time; keep a human-readable message even when kind is unknown. Merge with Merge Pull Request when verdict is "mergeable" and you intend to land the change.

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