Skip to main content

Command Palette

Search for a command to run...

API

Origin API

Origin 是 Cursor 的代码托管平台。其公开的 REST API 可让应用和工具与 Origin 仓库、提交、检查、PR 和应用安装协同工作。

  • Origin 应用使用应用 JWT 和安装访问令牌进行身份验证。请参阅身份验证。
  • 查看完整的 OpenAPI 规范，了解详细的架构和示例。
  • 智能体可以加载 llms.txt 索引，或在 llms-full.txt 中以 Markdown 格式加载完整参考。

概述

Origin 应用采用 OAuth 风格的安装授权流程和 GitHub App 风格的身份验证模型：

  1. 应用使用其 Ed25519 私钥为短期有效的 EdDSA JWT 签名。
  2. 应用使用该 JWT 和安装 ID 换取短期有效的安装访问令牌 (oit_…) 。
  3. 安装令牌可在该安装已获批准的仓库和权限范围内调用代码仓库 API，并通过 HTTPS 对 Git 进行身份验证。
  4. Origin 会向应用注册的 webhook URL 发送已签名的 webhook 投递记录。

基础 URL

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

参考中的端点路径均包含完整的 /v1/origin 前缀。

协议约定

请求和响应均使用 application/json。JSON 字段名采用 camelCase。时间戳采用 RFC 3339 格式的 string。Protobuf 64 位整数 (包括 PR 编号和版本号) 在 JSON 中表示为 string。

响应会保留处于默认值的字段，而不会将其丢弃，因此 false 布尔值、0 数值、空字符串和空数组都会出现在响应体中。请直接读取字段值本身，而不要把缺失的 key 当作默认值。文档中标注为不出现或被省略的字段在合约中是可选的，未设置时不会出现在响应体中。

入门

访问 Origin

Origin CLI

安装 Origin CLI 并登录：

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

克隆已有代码仓库：

origin repo clone '{ownerSlug}/{repoName}'# 或直接使用 gitgit clone 'https://origin.cursor.com/{ownerSlug}/{repoName}.git'

应用通过 Git HTTPS 身份验证 使用安装访问令牌克隆，而非使用用户登录。

安装

将以下内容发送给客户工作区管理员：

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
参数必填描述
client_id是Origin 应用 ID。
scope是以空格分隔的权限范围。会自动添加 repository:metadata:read。
redirect_uri合作伙伴发起安装时必填已注册的准确回调 URI。
state强烈建议作为安装回执的 state 声明回显的随机防伪值。重定向前生成，并在回调时验证该声明。
summary否同意授权时显示的简短说明。
include_granted_scopes否当值为 true 时，保留现有授权，仅请求新增权限范围。

工作区管理员选择目标所有者、批准的权限范围，以及所有仓库或选定的仓库。仓库访问权限由客户而非应用控制。

批准后，Origin 会重定向到已注册的回调地址：

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

验证安装回执，然后存储其 sub 声明中的安装 ID。签发安装访问令牌时需要用到它。

安装有以下两种仓库选择模式：

  • all：该安装可访问所选目标拥有的所有仓库。
  • selected：该安装只能访问工作区管理员选择的仓库。

两种模式均涵盖镜像仓库和原生 Origin 仓库，因此镜像会显示在 GET /installation/repos 中，并且可以被选中。镜像在成为稳定的出站镜像之前为只读：请参阅镜像仓库。

使用安装令牌调用 GET /installation/repos，即可查看该安装可访问的仓库。应用 JWT 端点可列出、查看和删除该 App 的安装。删除安装后将无法再签发新 token。

安装回执

installation_receipt 是由 Origin 签名的短期有效紧凑型 JWT，用于证明安装批准来自 Origin，而非伪造的重定向，并携带回调所需的全部信息。Cursor 不会在缺少此凭据时进行重定向，因此外部回调始终会携带它。

JOSE 请求头：

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

声明：

{  "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",    "displayName": "Jane Doe"  },  "state": "ORIGINAL_VALUE"}
  • aud 是您的应用 ID，sub 是签发安装访问令牌时使用的安装 ID。
  • namespace_id 是 app 所安装 namespace 的稳定 ID。
  • installedBy 用于标识执行此次安装或重新同意的用户。它描述当前操作，因此在重新同意时，可能与 获取 App Installation 中持久的 installedBy 不同。当账户设有名称时，它会携带 displayName，但绝不会携带 handle；请改为从 REST 响应或 webhook 负载中读取 handle。
  • 回执在签发五分钟后过期。每份回执的 jti 均唯一。
  • 仅当安装 URL 携带非空 state 时，才会包含 state，其值与该 state 相同。请将其与重定向前生成的防伪值进行匹配。

信任回调前，请先验证回执：根据 kid 请求头从 JWKS 获取签名密钥，要求 alg 为 EdDSA、typ 为 origin-installation-receipt+jwt，并验证签名、iss、aud 和 exp。验证失败时，拒绝该回调。

该回执不是安装访问令牌。切勿将其作为 Bearer 凭据发送；请改为通过 创建安装访问令牌 签发安装令牌。

身份验证

使用 Bearer 方案发送 REST 凭据。每个端点 的 Auth badge 列出了其接受的凭据类型：

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

生成应用签名密钥

Origin 应用使用 Ed25519 密钥对进行认证。在本地生成密钥对，然后仅将公钥注册到 cursor.com/codebase/settings/apps。每个应用最多可拥有 10 个当前有效的签名密钥。

使用 OpenSSL 创建 PKCS#8 私钥和 PEM SPKI 公钥：

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

公钥文件以 -----BEGIN PUBLIC KEY----- 开头。添加签名密钥时，请粘贴该 PEM。请仅使用对应的私钥签署应用 JWT。

应用 JWT

使用与应用的一个当前有效的签名密钥配对的 Ed25519 私钥签署短期有效的 JWT。按照生成应用签名密钥中的说明生成该密钥对。

JOSE 请求头：

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

声明：

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

将 iss 和 kid 设为应用 ID，并将有效期设为约五分钟。

Authorization: Bearer APP_JWT

使用应用 JWT 执行应用级操作，例如读取应用元数据、管理安装、签发安装令牌，以及恢复 Webhook 投递记录。

安装令牌

使用应用 JWT 调用 POST /app/installations/{installationId}/access_tokens。安装令牌以 oit_ 开头。

Authorization: Bearer oit_...

响应中包含 expiresAt。请按需签发 token，在到期前刷新，将其视为密码，切勿记录到日志中。

移除该安装或删除应用会使其安装令牌在 expiresAt 前失效。REST API 和 Git over HTTPS 随后会以 401 拒绝该令牌。请勿使用同一令牌重试；必须重新安装应用后才能签发可用令牌。

安装令牌的权限不得超出该安装获批的权限范围或仓库访问权限。你可以将安装令牌限制为更少的 scopes 或 repositoryIds。空数组或省略数组将继承完整的安装授权。

对限定在仓库范围内的操作使用安装令牌，包括 PR、check-run 写入操作以及通过 HTTPS 使用 Git。

Git HTTPS 身份验证

安装访问令牌用于通过 HTTPS 验证 Git 身份。Git 端点使用 HTTP Basic 认证：密码为安装令牌，用户名为 x-access-token。Bearer 凭据应仅用于 REST API；Git HTTPS 会拒绝此类凭据。

请在执行 Git 操作前立即通过 创建安装访问令牌 签发令牌。令牌最长有效期为 15 分钟。

克隆、获取和拉取需要 repository:contents:read。推送需要 repository:contents:write。令牌的授权范围必须包含目标代码仓库。

推送还要求代码仓库所有者有资格向 Origin 写入，这与创建代码仓库的要求相同。用户所有者必须使用 Pro、Pro Student、Pro+、Ultra 或 Start 方案。团队所有者必须拥有有效的付费团队方案、未使用隐私模式 (旧版) ，且 Origin 未被团队管理员关闭。向所有者不符合条件的代码仓库推送会返回 403。克隆、获取和拉取不受此要求限制。

从 Get Repo 或 列出应用安装可访问的仓库 获取 cloneUrl。GitHub 风格的路径 (https://origin.cursor.com/OWNER_SLUG/REPO_NAME.git) 和旧版 /git/ 路径均可用于克隆。

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

将令牌嵌入 URL 会使其存储在 .git/config 中。克隆成功后，重写远程地址，避免后续命令重复使用已过期的机密信息：

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

为避免令牌出现在远程 URL 中，请通过 Git's 凭据助手传入令牌：

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"

Origin CLI 凭据助手用于用户登录。应用集成会按此处所示传递安装令牌。请将令牌视为密码，切勿将其写入日志；如果作业仍需访问 Git，请在 expiresAt 到期前签发新的令牌。

对于镜像仓库，安装令牌可用于克隆、获取和拉取；在镜像成为稳定的出站镜像前，Origin 会拒绝 git push 并返回 403。请参阅镜像仓库。

用户认证的 CLI 请求

使用 origin api 发起用户认证的请求。若需交互式会话，请通过浏览器登录：

origin auth loginorigin api /repos/OWNER_SLUG/REPO_NAME/pulls

对于非交互式会话，请在 Cursor Dashboard → API Keys 中获取个人用户 API 密钥并提供：

export CURSOR_API_KEY="YOUR_PERSONAL_USER_API_KEY"origin api /repos/OWNER_SLUG/REPO_NAME/pulls

CLI 会用个人 API 密钥换取一个短期有效的用户访问令牌，然后在 Authorization 请求头中发送该令牌。请勿将 API 密钥本身发送到 Origin 端点。应用集成应改用应用 JWT 和安装访问令牌。

发现和签名密钥

Origin 会发布无需认证的发现元数据及其当前有效的签名密钥。这些密钥也用于签署 webhook 投递记录和安装回执。

发现元数据中包含颁发方和 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 返回有效的 Ed25519 JWK：

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"    }  ]}

缓存 JWKS。/keys 会发送 Cache-Control: public, max-age=600, stale-if-error=600，因此可复用缓存的响应 10 分钟，然后刷新；如果刷新失败，最多可再继续使用上一次有效的密钥 10 分钟，之后验证失败。此外，遇到没有任何密钥能验证的签名时也应刷新，这会移除已退役的密钥 ID。密钥每周轮换。

Webhook 签名不含密钥 ID，因此验证时应依次尝试所有有效的 Ed25519 密钥。安装回执会在其 JOSE 请求头中携带签名密钥的 kid，因此可直接解析用于验证回执的密钥。

权限范围

仅请求应用所需的最低权限范围。repository:metadata:read 以及应用或安装元数据访问权限会自动授予，无需单独添加到安装 URL。

权限范围允许的操作
repository:metadata:read读取代码仓库元数据。自动添加。
repository:contents:read读取提交、分支、内容、比较文件和底层 Git 对象。搜索文件文本。下载代码仓库归档文件。通过 Git HTTPS 克隆、获取和拉取。将镜像代码仓库与其上游源同步。
repository:contents:write通过 Git HTTPS 推送。合并 PR。通过 Git 数据端点创建分支并提交文件更改。重新请求检查运行。
repository:pull_requests:read读取 PR、修改的文件、PR 提交、已分配的标签和合并资格。
repository:pull_requests:write创建和更新 PR。分配和移除 PR 标签。
repository:pull_requests:reviews:read读取 PR 评论、评论线程、已提交的评审和请求的审阅人。
repository:pull_requests:reviews:write创建和更新评论；解决和重新打开评论线程；创建、更新和撤销评审；请求和移除审阅人。
repository:checks:read读取检查套件、运行和检查运行注释。
repository:checks:write创建和更新检查套件和运行。追加检查运行注释。
repository:labels:read读取代码仓库拥有的标签定义。
repository:labels:write创建、更新和删除代码仓库标签定义。
repository:rulesets:read读取代码仓库规则集。
repository:rulesets:write创建、更新和删除代码仓库规则集。
repository:settings:read读取直接在代码仓库上持有的授权。
repository:settings:write更新代码仓库设置：默认分支、可见性、合并方式以及自动删除头分支。更新或插入以及删除代码仓库上的授权。
namespace:settings:read读取直接在所有者上持有的授权。
namespace:settings:write更新或插入以及删除所有者上的授权。

请求 :write 权限范围也会授予对应的 :read 权限范围，因此 repository:labels:write 包含 repository:labels:read，无需同时列出两者。反之则不成立：读取权限范围绝不会授予写入权限。

安装令牌只能进一步缩小这些已授予的权限，不能添加工作区管理员未批准的权限范围或代码仓库。

镜像状态更改不在此表范围内。转换代码仓库镜像、强制代码仓库镜像切换 和 Detach Repo Mirror 需要 repository:mirror:write 或 repository:mirror:delete，应用无法在安装时请求这些权限：它们由 Cursor 用户凭据携带，且调用方还必须在镜像的上游源上拥有该代码仓库的管理权限。

出于同样的原因，应用管理也不在此表范围内。创建应用 需要 namespace:apps:create，List Namespace Apps 需要 namespace:apps:read，Get App 需要 app:settings:read，而 Update App、Add App Signing Key 和 Revoke App Signing Key 需要 app:settings:write。发布者在 Cursor 用户凭据上持有这些权限；应用无法为自身请求它们。

该表涵盖应用在安装时请求的权限范围。要查找单个操作所需的权限范围，请参阅其在 OpenAPI 规范中的 x-origin-scopes 扩展。该扩展涵盖所有操作，包括凭据本身附带而非来自安装授权的 app、installation 和 namespace 权限范围。若某个操作所需的权限范围全部随凭据附带，其扩展会标记为 ambient: true：无需为其请求任何权限，出示正确的凭据即可。

镜像仓库

安装对原生 Origin 代码仓库和稳定出站镜像拥有的所有权限范围均有效。对于处于其他任何镜像状态的代码仓库，仅以下两个权限范围有效：

  • repository:metadata:read
  • repository:contents:read

无论工作区管理员批准了哪些权限，该代码仓库上的其他所有权限范围都会返回 403。通过 REST API，仍可读取代码仓库和内容、比较 commit 以及使用 Sync Mirror，而 Origin 会拒绝 PR、评审、评论、检查、规则集及所有写入操作。通过 Git HTTPS，clone、fetch、pull 和下载 LFS 文件仍可正常进行，而 Origin 会拒绝 push 和上传 LFS 文件。

将代码仓库移出该状态需要使用用户凭据执行，而非安装可执行的操作：转换代码仓库镜像 可推进镜像方向，强制代码仓库镜像切换 可切换至上游源，而无需将有差异的 refs 推送回去，Detach Repo Mirror 则会永久断开镜像。

代码仓库上的 mirror object 并不能表明是否允许写入。正在过渡中的镜像可能会将 mirror.status 报告为 outbound，但仍处于只读状态，因此应以 403 为准，而不要根据 mirror.status 进行分支判断。

速率限制

Origin API 对每个主体采用共享的积分预算，并按滚动的一分钟窗口重置。每种已认证主体类型都有各自的预算：

主体默认预算
安装访问令牌3,000 点数/分钟
应用 JWT6,000 点数/分钟
Cursor 用户或服务账户600 点数/分钟

每个端点都会在处理程序运行前从该预算中扣除固定点数。身份验证或授权失败不扣除点数。

成本操作
0获取速率限制。仅返回状态；不消耗点数。
1大多数读取端点，以及创建安装访问令牌
5常规写入操作，以及以下开销较大的读取操作：获取提交、列出提交文件、列出比较文件、列出 PR 文件、获取代码仓库 Tarball 和 搜索内容
10创建应用、创建代码仓库、从文件创建提交、合并 PR、获取 PR 可合并性、转换代码仓库镜像 和 强制代码仓库镜像切换

Cursor 可为设计合作伙伴提高每个应用的每分钟预算。如果您的集成需要更高的限额，请联系 Cursor。

响应头

计费响应和 获取速率限制包含以下请求头：

请求头描述
X-RateLimit-Limit当前窗口中此主体可用的点数
X-RateLimit-Remaining当前窗口中剩余的点数
X-RateLimit-Used当前窗口中已消耗的点数
X-RateLimit-Reset窗口重置时的 Unix 时间戳 (UTC 秒)
X-RateLimit-Resource共享公共 API 预算始终为 core

X-RateLimit-Reset 表示从响应时间起算的完整 60 秒窗口。计数窗口从一连串请求中的第一个计费请求开始，而非按自然分钟边界划分。

超出限额

当请求会超出预算时，API 会返回 HTTP 429，并包含：

  • Retry-After：重试前需等待的秒数 (60)
  • 相同的 X-RateLimit-* 请求头，其中 X-RateLimit-Remaining 设为 0
{  "code": 8,  "message": "Rate limit exceeded: 3000 points per minute for this installation. Retry after 60s.",  "details": []}

重试前，请等待 Retry-After 指定的时间，或等到 X-RateLimit-Reset。当多个调用方共用一个安装令牌时，请使用带抖动的退避策略。

查看剩余配额

调用 获取速率限制 可在不消耗点数的情况下获取当前配额。响应体与共享 core 资源的 X-RateLimit-* 请求头相对应。

通用约定

分页

分页端点接受：

  • pageSize：默认值为 30，最大值为 100。
  • pageToken：由上一页返回的不透明 token。请勿解析或自行构造。

响应使用资源特定的集合字段和 nextPageToken。没有下一页时，该字段为空。公开列表响应不包含总数。页面 token 与其来源资源和筛选条件绑定。筛选条件变更后，请重新开始分页。无效或不匹配的非空 token 将返回 400。

错误

错误响应采用 Google RPC 风格的响应体：

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

常见的 HTTP 状态码包括 400、401、403、404、429、500 和 503。部分 Git 数据库操作在代码仓库状态冲突时还会返回 409。有关 429 请求头和重试行为，请参阅速率限制。

根据 HTTP 状态码和 code 对错误进行分支处理。将 message 视为面向开发者的文本。

404 永远不会区分资源不存在和应用无法访问资源这两种情况。应将其理解为 "此安装不可用"，而非资源不存在的证明。

details 包含具有明确类型的条目：参数无效时的 google.rpc.BadRequest 字段违规，以及每个错误中的 google.rpc.RequestInfo 条目。Origin 可随时添加详细信息类型，因此请忽略集成无法识别的条目。

每个错误响应都会在两个位置携带请求 ID：X-Request-ID 响应请求头中，以及 details 中的 google.rpc.RequestInfo 条目。Origin 会回显你发送的 x-request-id，若未发送则会生成一个。即使 message 是不透明的内部错误，也会提供 RequestInfo 条目，因此就失败的调用联系 Cursor 时，请提供请求 ID。

/v1/origin 下未匹配的路径，以及在已知路径上使用错误 method 的请求，会返回相同的响应体，而非通用 router 错误。消息会注明 method 和路径，且绝不会回显 query string。

代码仓库路径

代码仓库范围内的路径使用 {ownerSlug}/{repoName} 格式，包含所有者 slug 和代码仓库名称。两个部分的解析均不区分大小写，因此无论使用何种大小写都可定位到该代码仓库。响应返回的是存储的名称和 slug，而非你发送时使用的大小写；Git HTTPS URL 也以相同方式解析。比较代码仓库名称时应忽略大小写，并从 Get Repo 获取规范的大小写形式。

每个代码仓库范围内的路径也可以使用代码仓库的稳定 ID 来代替这一组合：将 _ 作为所有者 slug，并将 ID 作为代码仓库名称，例如 GET /v1/origin/repos/_/REPO_ID。从 Get Repo 的 id 字段读取 ID。保留值 _ 不能被声明为所有者 slug，因此这两种形式永远不会冲突。在 Connect 或 JSON 请求中，将 ownerSlug 设为 _，并将 name 设为 ID。

ID 形式在重命名后仍然有效，因此是定位代码仓库的稳定方式。它本身不授予任何权限：Origin 将 ID 解析为代码仓库后，你的 app 仍需要在该代码仓库上具有相同的 scope。你的 app 无法访问的 ID 会返回与不存在的 ID 相同的 404 响应体，因此响应绝不会确认某个代码仓库是否存在。格式错误的 ID 返回 400。创建代码仓库 仅接受所有者 slug，并拒绝 _。

资源引用

资源快照包含资源当前的字段。容器上下文使用紧凑引用，避免重复完整的资源：

  • RepositoryReference 用于标识代码仓库。
  • PullRequestReference 用于标识 PR，并嵌套其代码仓库引用。
  • ThreadReference 用于标识包含 PR 评论的线程。
  • OriginActor 将公共操作人标识为 user、app 或 serviceAccount 之一。仅存在一个变体；请从该变体中读取身份信息。

当前限制

  • 合作伙伴 API 不支持在命名空间范围内列出或创建代码仓库。请通过安装来发现代码仓库。
  • 提交 比较返回摘要数据，而不是嵌入式 提交 列表。修改的文件有自己的分页端点，列出比较文件。
  • 线程仅能在解决操作中被引用。没有直接列出线程的端点；请从其包含的评论中读取它们。
  • 推送 Webhook 不包含完整的 提交 列表。
  • PR 合并支持原生 Origin 仓库，不支持镜像代码仓库。
  • 镜像代码仓库在成为稳定的出站镜像之前，对安装为只读。参阅镜像代码仓库。

实施检查清单

  • 将 Ed25519 私钥存储在机密信息管理服务中，并有计划地轮换密钥。请参阅生成应用签名密钥。
  • 验证安装回调中的安装回执，并从其声明中读取安装 ID 和 state。
  • 使用短期有效的 应用 JWT，并在需要时签发安装令牌。
  • 对代码仓库范围的 API、check-run 写入操作和 Git HTTPS 使用安装令牌，而非 应用 JWT。
  • 仅请求最低限度的 权限范围 和代码仓库访问权限。
  • 将 页面 token 视为 不透明，并在筛选条件变更时重新开始分页。
  • 保持 check key 值稳定且易读。每次 retry 均使用新的不可变 externalId，更新时使用递增的 externalUpdatedAt 值。
  • 解析前，使用原始请求体验证 webhook 签名。
  • 使用 webhook-id 对投递进行去重，并在返回 2xx 后异步处理。
  • 忽略未知的 JSON 字段，以实现前向兼容。
  • 遵守 Retry-After 和 X-RateLimit-* 请求头。使用 获取速率限制 在不消耗点数的情况下监控剩余点数。

端点参考

下载OpenAPI 规范，查看完整的组件架构。该文档将 https://api.cursor.com 声明为服务器，并定义了 bearerAuth HTTP Bearer 安全方案；每个操作都会列出该操作可能返回的响应代码，以及请求和响应示例。每个操作还带有 x-origin-scopes 扩展：scopes 表示该操作所需的作用域，tokenTypes 表示它接受的凭据类型。路径参数与 URL 中使用的名称相同，即 ownerSlug 和 repoName。每个操作都带有唯一的 operationId；当一个操作对应两种 URL 形式时，第二种形式的 id 会带上 _2 后缀，例如 OriginService_GetRepoTarball_2。

JSON 代码段展示与架构相符的占位符值。响应字段描述反映 OpenAPI 架构和当前平台契约。

应用和安装

获取速率限制

GET/v1/origin/rate_limit
AuthApp JWTInstallation tokenUser access token

返回已认证主体当前的公共 API 速率限制状态。

访问此端点不会消耗速率限制点数。响应包含该主体与其他公共 API 端点共用的每分钟点数预算。请参阅速率限制。

响应字段

resources object

已认证主体的速率限制资源。

resources.core object

公共 API 端点共用的每分钟点数预算。

resources.core.limit integer

当前时间窗口内可用的最大点数。

resources.core.remaining integer

当前时间窗口内剩余的点数。

resources.core.reset integer

当前时间窗口重置时的 Unix 时间戳 (UTC 秒) 。

resources.core.used integer

当前时间窗口内已消耗的点数。

rate object

resources.core 的别名。新客户端应优先使用 resources.core。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/rate_limit' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "resources": {    "core": {      "limit": 6000,      "remaining": 5994,      "reset": 1785682800,      "used": 6    }  },  "rate": {    "limit": 6000,    "remaining": 5994,    "reset": 1785682800,    "used": 6  }}

获取已认证应用

GET/v1/origin/app
AuthApp JWT

返回已认证应用的元数据。

响应字段

id string

用作 JWT 颁发方和密钥 ID 的 Origin 应用标识符。

displayName string

便于阅读的应用显示名称。

webhookUrl string

用于接收应用 Webhook 投递记录的已注册 HTTPS URL。

events array

为应用配置的 Webhook 事件订阅。

createdAt string

应用创建时的 RFC 3339 时间戳。

updatedAt string

应用元数据最近更新时的 RFC 3339 时间戳。

installationRedirectUris array

已注册的安装回调 URI；非本地回调必须完全匹配且使用 HTTPS。

namespaceSlug string

拥有该应用的 namespace 的 slug。

description string

发布方提供的应用描述。未设置时为空。

websiteUrl string

发布方网站。未设置时为空。

defaultScopes array

安装应用时提供的默认作用域，以目录作用域字符串表示。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/app' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "id": "app_01k2ja2000e0080000000000a1",  "displayName": "CI Status Bot",  "webhookUrl": "https://ci.acme.dev/webhooks/origin",  "events": [    "pull_request.created",    "pull_request.merged"  ],  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z",  "installationRedirectUris": [    "https://ci.acme.dev/origin/setup"  ],  "namespaceSlug": "acme",  "description": "Posts CI status on pull requests.",  "websiteUrl": "https://ci.acme.dev",  "defaultScopes": [    "repository:contents:read",    "repository:pull_requests:read"  ]}

列出应用安装

GET/v1/origin/app/installations
AuthApp JWT

列出已认证应用的安装。

查询参数

pageSize integer

要返回的最大安装数。未设置或为 0 时默认值为 30。超过 100 的值将被限制为 100。

pageToken string

上一响应的 next_page_token 返回的不透明游标。第一页为空。

响应字段

installations array

已通过身份验证的应用拥有的安装页面。

installations[].id string

应用存储并用于签发安装访问令牌的安装标识符。

installations[].appId string

已安装应用的标识符。

installations[].target object

客户为此安装选择的负责人。

installations[].target.slug string

用于 URL 的所有者 slug，与所有者 ID 一起用于识别仓库所有者。

installations[].target.id string

Origin 所有者标识符。

installations[].target.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

installations[].createdAt string

RFC 3339 格式的安装创建时间戳。

installations[].updatedAt string

最新安装更新的 RFC 3339 时间戳。

installations[].repoSelectionMode string

代码仓库授权模式；必须为 all 或 selected。

installations[].scopes array

已获批准的安装范围。

installations[].installedBy object

最初安装该应用的用户，而非最近一次重新同意的操作者。仅用于输出。当无法读取该用户记录时将缺失。

installations[].installedBy.id string

用户的公开标识符，前缀为 user_。

installations[].installedBy.email string

该用户的电子邮件地址。

installations[].installedBy.displayName string

用户的显示名称：账户的名字和姓氏以空格连接，与产品呈现的名称相同。若账户没有名称则省略。

installations[].installedBy.handle string

用户已认领的个人资料账号，不含 @ 前缀。仅在该资料公开可见时提供；否则省略。

installations[].suspendedAt string

安装处于暂停状态时设置的 RFC 3339 时间戳。安装处于活跃状态时省略。

installations[].deletedAt string

安装被删除的 RFC 3339 时间戳。仅在 installation.deleted webhook 快照中携带；已删除的安装无法再通过 API 解析，因此该端点不会返回该字段。

nextPageToken string

用于获取下一页的不透明游标；没有更多页面时为空。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/app/installations' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "installations": [    {      "id": "inst_01k2ja2000e0080000000000b2",      "appId": "app_01k2ja2000e0080000000000a1",      "target": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      },      "createdAt": "2026-08-01T09:30:00Z",      "updatedAt": "2026-08-02T14:45:00Z",      "repoSelectionMode": "selected",      "scopes": [        "repository:contents:read",        "repository:pull_requests:read"      ]    }  ]}

获取应用安装

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

返回已认证应用的单个安装。

repoSelectionMode 为 all 或 selected。

路径参数

installationId string 必填

安装标识符。

响应字段

id string

应用存储并用于签发安装访问令牌的安装标识符。

appId string

已安装应用的标识符。

target object

客户为此安装选择的所有者。

target.slug string

用于 URL 的所有者 slug，与所有者 ID 一起用于标识代码仓库所有者。

target.id string

Origin 所有者标识符。

target.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

createdAt string

RFC 3339 格式的安装创建时间戳。

updatedAt string

RFC 3339 格式的最新安装更新时间戳。

repoSelectionMode string

代码仓库授权模式；必须为 all 或 selected。

scopes array

已为该安装批准的作用域。

installedBy object

最初安装该应用的用户，而非最近一次重新授权的操作者。仅输出。若无法再读取该用户记录，则不返回。

installedBy.id string

用户的公开标识符，以 user_ 为前缀。

installedBy.email string

用户的电子邮件地址。

installedBy.displayName string

用户的显示名称：账户的名字和姓氏以空格连接，与产品显示的名称一致。账户没有名称时省略。

installedBy.handle string

用户已认领的个人资料句柄，不含 @ 前缀。仅在该个人资料公开可见时提供；否则省略。

suspendedAt string

安装被暂停期间设置的 RFC 3339 格式时间戳。安装处于活跃状态时省略。

deletedAt string

RFC 3339 格式的安装删除时间戳。仅在 installation.deleted webhook 快照中携带；已删除的安装无法再通过 API 解析，因此此端点永远不会返回该字段。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/app/installations/INSTALLATION_ID' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "id": "inst_01k2ja2000e0080000000000b2",  "appId": "app_01k2ja2000e0080000000000a1",  "target": {    "slug": "acme",    "id": "ns_01k2ja2000e0080000000000p3",    "type": "team"  },  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z",  "repoSelectionMode": "selected",  "scopes": [    "repository:contents:read",    "repository:pull_requests:read"  ]}

删除应用安装

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

删除属于已认证应用的安装，并阻止签发新的安装令牌。已签发的短期令牌在过期前可能仍然有效 (最长 15 分钟) 。响应体为空。

路径参数

installationId string 必填

要删除的安装的唯一标识符。从 URL 路径中获取；该安装必须属于已认证应用。

响应字段

成功的请求不返回响应体。

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

响应：

204 No Content

创建安装访问令牌

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

为已认证应用创建安装访问令牌。

需要使用应用 signing-JWT 身份验证，与 GetAuthenticatedApp 相同。令牌仅适用于指定的安装，该安装必须属于已认证应用。调用方可将令牌权限缩小为该安装所接受权限范围和可访问代码仓库的子集。

repositoryIds 可以指定镜像代码仓库。生成的令牌携带该安装的权限范围，Origin 仍会对每个请求应用镜像限制：请参阅镜像代码仓库。

路径参数

installationId string 必填

令牌适用的安装的唯一标识符。从 URL 路径中获取；该安装必须属于已认证应用。

请求体

scopes array

授予令牌的权限范围 string。值必须唯一，且包含在该安装所接受的权限范围中。留空或省略时，继承完整的权限范围授权。

repositoryIds array

授予令牌访问权限的代码仓库 ID。值必须唯一、可由该安装访问，且最多包含 50 项。留空或省略时，继承所有可访问的代码仓库。

响应字段

token string

带有 oit_ 前缀的短期安装凭证。

expiresAt string

RFC 3339 过期时间；令牌最长 15 分钟后过期，且不会比用于签发它的应用 JWT 存活更久。
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 '{  "scopes": [    "repository:contents:read",    "repository:pull_requests:read"  ],  "repositoryIds": [    "repo_01k2ja2000e0080000000000q4"  ]}'

响应结构：

{  "token": "oit_2v8xkq4m1c7p9t3w5y0z6r4b",  "expiresAt": "2026-08-01T10:30:00Z"}

列出应用安装可访问的代码仓库

GET/v1/origin/installation/repos
AuthInstallation token

列出已认证应用安装可访问的代码仓库。

需要由 CreateInstallationAccessToken 签发的安装访问令牌 (oit_) 。

合作伙伴可通过此端点发现其仓库。列表条目为简要的仓库摘要；如需完整的时间戳，请使用 Get Repo。Get Repo 包含仅供输出的 cloneUrl。

结果中包含镜像仓库。镜像在成为稳定的出站镜像之前为只读：参见镜像仓库。

查询参数

pageSize integer

返回的最大仓库数。未设置或为 0 时默认为 30。超过 100 的值将被限制为 100。

pageToken string

来自先前响应的 next_page_token 的不透明游标。第一页时为空。

响应字段

repositories array

精简的代码仓库摘要；如需完整时间戳，请使用 get-repository。

repositories[].id string

Origin 仓库标识符。

repositories[].name string

仓库在其所有者下的名称。

repositories[].fullName string

所有者和仓库名称的组合，例如 acme/api。

repositories[].owner object

仓库的所有者引用。

repositories[].owner.slug string

用于 URL 的所有者 slug，与所有者 ID 一起用于标识代码仓库的所有者。

repositories[].owner.id string

源所有者标识符。

repositories[].owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

repositories[].defaultBranch string

代码仓库默认分支名称。

repositories[].mirror 对象

镜像元数据。原生仓库以及镜像首次同步就绪前不包含此字段。

repositories[].mirror.source string

镜像源。允许的值：github。

repositories[].mirror.sourceId string

由来源分配的不透明仓库标识符。

repositories[].mirror.status string

迁移过程中有效的镜像方向，直到切换完成。允许的值：inbound、outbound。

repositories[].visibility string

代码仓库可见性。允许的值：internal、private。

repositories[].allowMergeCommit boolean

PR 是否可以以合并提交的方式合入。

repositories[].allowSquashMerge boolean

PR 是否可以通过压缩合并 (squash merge) 的方式合入。

repositories[].deleteBranchOnMerge boolean

合并时是否自动删除主分支。

nextPageToken string

下一页的不透明游标；当没有更多页面时为空。

repoSelectionMode string

指示该安装是授予对所有仓库的访问，还是仅授予对部分选定仓库的访问。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/installation/repos' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "repositories": [    {      "id": "repo_01k2ja2000e0080000000000q4",      "name": "rocket",      "fullName": "acme/rocket",      "owner": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      },      "defaultBranch": "main",      "createdAt": "2026-08-01T09:30:00Z",      "updatedAt": "2026-08-02T14:45:00Z",      "pushedAt": "2026-08-02T14:45:00Z",      "cloneUrl": "https://origin.cursor.com/git/acme/rocket.git"    }  ],  "repoSelectionMode": "selected"}

列出 Webhook 投递记录

GET/v1/origin/app/webhook/deliveries
AuthApp JWT

列出已认证应用的 Webhook 投递记录，按最新优先排序。

一次投递是欠某个应用的一次事件；其 id 是接收方看到的 webhook-id 请求头的值。delivered=false 是恢复谓词：它会选择所有从未收到 2xx 的投递，包括在故障期间其重试阶梯耗尽的投递。

投递在创建后七天内可列出，且仅在您的应用在该投递所属命名空间中有活动安装时可见。面向应用的生命周期事件 (例如 installation.deleted) 在其所描述的卸载发生后仍然可见。

查询参数

delivered 布尔值

根据 delivered_at 进行比较。delivered=false 是恢复谓词：它在服务器端评估，因此不会像调用方提供的时间窗口那样，在故障期间重试阶梯耗尽时悄然漏掉某次投递。

eventType string

精确的事件类型，例如 pull_request.created。

installationId string

筛选为单一安装 (WebhookDelivery.installation.id) 。

createdAfter string

限制投递记录的创建时间范围。仅用于浏览，不用于恢复。

createdBefore string

pageSize integer

未设置或为 0 时默认为 30。大于 100 的值会被限制为 100。

pageToken string

来自先前响应的 next_page_token 的不透明游标。第一页为空。

响应字段

deliveries 数组

已验证应用的 Webhook 投递记录，按最新的在前排列。每个投递 ID 即接收方看到的 webhook-id。

deliveries[].id 字符串

稳定的投递标识符，即接收方看到的 webhook-id 值；将其用作幂等键。

deliveries[].event 对象

此投递所携带的事件。

deliveries[].event.id string

底层 Origin 事件标识符。它也可能与稳定投递 ID 一同出现，但不是幂等键。

deliveries[].event.type string

投递中携带的、用于路由的事件 slug。

deliveries[].installation 对象

该投递所属的安装。id 是目标所有者当前的活动安装；如果不存在则不设置 (仅在卸载后的面向应用的生命周期事件中可能出现) 。

deliveries[].installation.id string

与 webhook 投递列表项关联的安装标识符。

deliveries[].installation.target 对象

被安装定位的所有者。

deliveries[].installation.target.slug string

面向 URL 的所有者 slug，与所有者 ID 一起用于识别仓库所有者。

deliveries[].installation.target.id string

源所有者标识符。

deliveries[].installation.target.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

deliveries[].createdAt string

投递创建时间戳，供 createdAfter 和 createdBefore 浏览筛选使用。

deliveries[].deliveredAt string

未设置表示 delivered=false：接收方从未以 2xx 响应确认此投递。

deliveries[].lastAttempt 对象

最近一次 HTTP 尝试 (如存在) ：其响应状态码、延迟、传输错误、触发原因和时间。

deliveries[].lastAttempt.id 字符串

Webhook 投递尝试的标识符。

deliveries[].lastAttempt.deliveryId string

与此次尝试关联的稳定投递标识符。

deliveries[].lastAttempt.trigger string

发送此次投递尝试的原因。允许的值：automatic、manual。

deliveries[].lastAttempt.responseStatusCode 整数

当 POST 未产生任何 HTTP 响应 (传输错误、超时) 时，未设置。

deliveries[].lastAttempt.latencyMs integer

投递尝试延迟 (以毫秒为单位) 。

deliveries[].lastAttempt.errorMessage string

未收到 HTTP 响应时的传输错误详情；否则为空。

deliveries[].lastAttempt.attemptedAt string

本次投递尝试的 RFC 3339 时间戳。

nextPageToken string

用于下一页的不透明游标；当没有更多页面时为空。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/app/webhook/deliveries' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "deliveries": [    {      "id": "whd_01k2ja2000e0080000000000j9",      "event": {        "id": "evt_01k2ja2000e0080000000000r5",        "type": "pull_request.created"      },      "installation": {        "id": "inst_01k2ja2000e0080000000000b2",        "target": {          "slug": "acme",          "id": "ns_01k2ja2000e0080000000000p3",          "type": "team"        }      },      "createdAt": "2026-08-01T09:30:00Z",      "deliveredAt": "2026-08-02T14:45:05Z",      "lastAttempt": {        "id": "wha_01k2ja2000e0080000000000k0",        "deliveryId": "whd_01k2ja2000e0080000000000j9",        "trigger": "automatic",        "responseStatusCode": 200,        "latencyMs": 182,        "attemptedAt": "2026-08-02T14:45:05Z"      }    }  ]}

批量重新投递 Webhook 投递记录

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

请求 Origin 重新发送投递记录。

该请求表示“确保这些记录中的每条都有一次发送正在进行”，而非“新增一次发送”。它会为每个唯一输入返回一个结果，不会因某个无效条目而使整个批次失败，因此单个过期 ID 不会阻塞恢复页中的其余记录。202 表示发送已排队；投递本身是异步的，因此请轮询 列出 Webhook 投递记录 查看结果。

请求体

deliveryIds array 必填

要重新发送的投递记录。最多 100 个唯一条目，与列出 Webhook 投递记录的 pageSize 上限一致。重复项会被移除，并保留首次出现的顺序。空列表或超过 100 个唯一条目将返回 InvalidArgument (HTTP 400)。

响应字段

results array

已接受的异步重新投递结果，每个唯一投递 ID 对应一个结果，结果为 queued、already_in_flight 或 not_found。

results[].deliveryId string

与此批次结果对应的请求中指定的稳定投递 ID。

results[].outcome string

重新投递处理结果：创建发送时为 queued，已有发送正在进行时为 already_in_flight，否则为 not_found。already_in_flight 表示成功，而非错误。not_found 包括未知 ID、早于七天保留期的 ID，以及未再安装您的应用的命名空间。
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": [    "whd_01k2ja2000e0080000000000j9"  ]}'

响应结构：

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

Ping Webhook

POST/v1/origin/app/webhook/pings
AuthApp JWT

向已认证应用的 webhook URL 发送测试投递，并返回接收方的响应情况。

配置应用时，可使用此操作验证接收方，无需等待真实事件。与 获取已认证应用 一样，需要使用应用 signing-JWT 进行身份验证。

接收方将收到生产环境格式的数据：相同的请求头和 v1ed 签名，可通过签名密钥验证；webhook-event-type 设为 ping，负载中会标明应用名称。ping 不关联任何安装，因此不包含 webhook-installation-id 请求头和信封中的 installationId。

Origin 会同步发送一次 ping，并在响应中返回结果。不会重试，且 ping 不属于域名事件：它不会出现在 列出 Webhook 投递记录 中，也无法重新投递。接收方处理失败会在响应中体现，而不会返回错误。未配置 webhook URL 的应用会返回 FailedPrecondition (HTTP 400) 。

请求体

请求不接受任何字段。请发送空 JSON 对象。

响应字段

deliveryId string

测试投递的 webhook-id，与接收方收到的请求头中的值一致。

eventId string

签名信封内的事件 ID，与 event.id 的值相同。

delivered boolean

接收方在投递超时前返回 2xx 状态时为 true。始终存在。

responseStatusCode integer

接收方返回的 HTTP 状态码；如果因连接失败或超时未收到响应，则为 0。始终存在。
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 '{}'

响应结构：

{  "deliveryId": "whd_01k2ja2000e0080000000000j9",  "eventId": "evt_01k2ja2000e0080000000000r5",  "delivered": true,  "responseStatusCode": 200}

获取应用

GET/v1/origin/apps/{appId}
Scopeapp:settings:readAuthUser access token

按标识符返回单个应用。这是供应用发布者使用的管理读取接口；Get Authenticated App 则是使用应用自身 JWT 凭据的等效自读取接口。

Path Parameters

appId string 必填

应用标识符，前缀为 app_。

Response Fields

id string

全局唯一的应用标识符，前缀为 app_。

displayName string

面向用户展示的应用名称。

webhookUrl string

已注册的 HTTPS URL，用于接收该应用的 Webhook 投递记录。应用不接收任何投递记录时为空。

events array

为该应用配置的 Webhook 事件订阅。

createdAt string

应用创建时间的 RFC 3339 时间戳。

updatedAt string

应用元数据最近一次更新时间的 RFC 3339 时间戳。

installationRedirectUris array

OAuth 安装回调允许列表：由应用发起的安装流程可返回的重定向 URI，在授权时进行精确匹配。

namespaceSlug string

拥有该应用的 namespace 的 slug。

description string

发布者提供的应用描述。未设置时为空。

websiteUrl string

发布者网站。未设置时为空。

defaultScopes array

安装该应用时提供的默认作用域，以目录作用域字符串形式表示。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/apps/{appId}' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "id": "app_01k2ja2000e0080000000000a1",  "displayName": "CI Status Bot",  "webhookUrl": "https://ci.acme.dev/webhooks/origin",  "events": [    "pull_request.created",    "pull_request.merged"  ],  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z",  "installationRedirectUris": [    "https://ci.acme.dev/origin/setup"  ],  "namespaceSlug": "acme",  "description": "Posts CI status on pull requests.",  "websiteUrl": "https://ci.acme.dev",  "defaultScopes": [    "repository:contents:read",    "repository:pull_requests:read"  ]}

更新 App

PATCH/v1/origin/apps/{appId}
Scopeapp:settings:writeAuthUser access token

更新应用的设置。省略的字段保持不变，且至少需提供一个可设置的字段。通过发送空字符串清除 webhookUrl 会禁用对外的 webhook 投递，并取消该应用待处理的投递；之后重新设置 URL 也不会恢复已取消的投递。

路径参数

appId string 必填

应用标识符，以 app_ 为前缀。

请求体

displayName string

新的面向用户的 app 名称。若提供该字段，则不能为空。

webhookUrl string

新的出站 webhook 投递 URL，必须是绝对 HTTPS URL。传入空 string 将禁用 webhook 投递，并取消该 app 待投递的记录。

events object

整体替换 webhook 事件订阅。省略该字段则保持不变。

events.events 数组

该 app 全新的完整 webhook event 订阅集合。传入空列表即可清除全部订阅。

description string

新的应用描述。省略则保持不变；传入空字符串将清除描述。

websiteUrl string

新的发布者网站。省略则保持不变；传入空字符串可清除该值。

installationRedirectUris object

整体替换 OAuth 安装回调允许列表。省略则保持不变。

installationRedirectUris.installationRedirectUris 数组

完整的新允许列表。传入空列表将清除该列表。

defaultScopes object

完全替换该 app 的默认安装作用域。省略此项则保持不变。

defaultScopes.scopes 数组

要设置的全新默认安装作用域集合。传入空列表可清除所有作用域。

响应字段

id string

全局唯一的应用标识符，以 app_ 为前缀。

displayName string

面向用户展示的 app 名称。

webhookUrl string

已注册的 HTTPS URL，用于接收该 app 的 Webhook 投递记录。若该 app 不接收任何投递，则为空。

events array

为该 app 配置的 webhook 事件订阅。

createdAt string

app 创建时间的 RFC 3339 timestamp。

updatedAt string

最近一次 app metadata 更新的 RFC 3339 timestamp。

installationRedirectUris 数组

OAuth 安装回调允许列表：由应用发起的安装可返回的重定向 URI，在授权时须完全匹配。

namespaceSlug string

拥有该 app 的 namespace 的 slug。

description string

由 publisher 提供的 app 描述。未设置时为空。

websiteUrl string

发布者网站。未设置时为空。

defaultScopes 数组

安装该 app 时提供的默认作用域，以 catalog 作用域 string 形式表示。
curl --request PATCH \  --url 'https://api.cursor.com/v1/origin/apps/APP_ID' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "webhookUrl": "https://ci.acme.dev/webhooks/origin-v2",  "events": {    "events": [      "pull_request.created",      "pull_request.merged",      "repository.pushed"    ]  }}'

响应结构：

{  "id": "app_01k2ja2000e0080000000000a1",  "displayName": "CI Status Bot",  "webhookUrl": "https://ci.acme.dev/webhooks/origin-v2",  "events": [    "pull_request.created",    "pull_request.merged",    "repository.pushed"  ],  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z",  "installationRedirectUris": [    "https://ci.acme.dev/origin/setup"  ],  "namespaceSlug": "acme",  "description": "Posts CI status on pull requests.",  "websiteUrl": "https://ci.acme.dev",  "defaultScopes": [    "repository:contents:read",    "repository:pull_requests:read"  ]}

添加应用签名密钥

POST/v1/origin/apps/{appId}/signing_keys
Scopeapp:settings:writeAuthUser access token

向应用添加一个签名密钥。应用可持有的当前有效的签名密钥数量有上限；超出上限后再添加密钥会返回 FailedPrecondition (HTTP 400) ，直到吊销其他密钥为止。若密钥已注册，则返回 AlreadyExists (HTTP 409 Conflict) 。

路径参数

appId string 必填

应用标识符，前缀为 app_。

请求体

publicKey string 必填

要添加到该应用签名密钥集合中的 PEM SPKI Ed25519 公钥。

响应字段

kid string

密钥 ID：该密钥 SPKI DER 编码的 SHA-256 摘要，以 base64url 编码表示。可用作 JWT 的 kid 请求头，也可用于吊销该密钥。

createdAt string

密钥注册时间的 RFC 3339 时间戳。
curl --request POST \  --url 'https://api.cursor.com/v1/origin/apps/APP_ID/signing_keys' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAq9zTf3hL6wXe1cVj0bYs5mKR8uDnG2oAaPp4NiEkKlM=\n-----END PUBLIC KEY-----"}'

响应结构：

{  "kid": "3q2xW9dK5fJm8vB1nY6cT0aZrQpLh4eGkVsN7uMxOdI",  "createdAt": "2026-08-02T14:45:00Z"}

吊销应用签名密钥

DELETE/v1/origin/apps/{appId}/signing_keys/{kid}
Scopeapp:settings:writeAuthUser access token

按密钥 ID 吊销应用签名密钥。使用已吊销密钥签名的应用 JWT 将无法再通过认证。最后一个当前有效的签名密钥无法吊销，此类请求会返回 FailedPrecondition (HTTP 400) 。响应体为空。

路径参数

appId string 必填

应用标识符，前缀为 app_。

kid string 必填

要吊销的签名密钥的密钥 ID。

响应字段

请求成功时不返回响应体。

curl --request DELETE \  --url 'https://api.cursor.com/v1/origin/apps/{appId}/signing_keys/{kid}' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应：

204 No Content

列出 命名空间 应用

GET/v1/origin/namespaces/{namespaceSlug}/apps
Scopenamespace:apps:readAuthUser access token

列出某个命名空间拥有的应用，最新的排在前面。响应仅包含用于展示的 metadata；如需读取某个应用的 webhook 配置，请使用 Get App。

路径参数

namespaceSlug string 必填

要列出其应用的命名空间的 slug。

Query Parameters

pageSize integer

返回的最大应用数量。未设置或为 0 时默认为 30。超过 100 的值会按 100 处理。

pageToken string

上一次响应中 next_page_token 返回的不透明游标。首页时为空。

响应字段

apps array

该命名空间拥有的应用的当前页。

apps[].id string

全局唯一的应用标识符，前缀为 app_。

apps[].displayName string

面向用户展示的应用名称。

apps[].description string

publisher 提供的描述。未设置时为空。

nextPageToken string

用于获取下一页的不透明游标；没有更多页时为空。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/namespaces/{namespaceSlug}/apps' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "apps": [    {      "id": "app_01k2ja2000e0080000000000a1",      "displayName": "CI Status Bot",      "description": "Posts CI status on pull requests."    },    {      "id": "app_01k2ja2000e0080000000000a2",      "displayName": "Deploy Bot",      "description": ""    }  ],  "nextPageToken": ""}

创建应用

POST/v1/origin/namespaces/{namespaceSlug}/apps
Scopenamespace:apps:createAuthUser access token

创建一个归属于某个 namespace 的 app。新建的 app 默认为私有。请在本地生成 Ed25519 key pair，并且只发送 public key；Origin 会将其存储，用于验证该 app 的 JWT。若 webhook URL、event type、重定向 URI 或 scope 无效，则返回 InvalidArgument (HTTP 400) 。

路径参数

namespaceSlug string 必填

将拥有该 app 的 namespace 的 slug。

请求体

displayName string 必填

面向用户展示的应用名称，不能为空。

publicKey string 必填

应用签名密钥对的 PEM SPKI Ed25519 公钥。参见生成应用签名密钥。

webhookUrl string

出站 webhook 投递 URL，需为绝对 HTTPS URL。留空表示该应用不接收任何 webhook 投递。

events array

webhook event 订阅，使用 Events 中的 event slug 表示。未知的 event type 会被拒绝。

description string

app 的简短描述。

websiteUrl string

发布者网站，须为绝对 HTTPS URL。

installationRedirectUris 数组

OAuth 安装回调允许列表：须为不含片段的绝对 HTTPS URI，并在授权时精确匹配。

defaultScopes 数组

安装应用时提供的默认作用域，采用目录作用域字符串格式，例如 repository:contents:read。安装仍可显式指定作用域。

响应字段

id string

全局唯一的应用标识符，以 app_ 为前缀。

displayName string

面向用户展示的 app 名称。

webhookUrl string

已注册的 HTTPS URL，用于接收该应用的 webhook 投递。若该应用没有任何投递，则为空。

events array

为该应用配置的 webhook 事件订阅。

createdAt string

app 创建时间的 RFC 3339 timestamp。

updatedAt string

最近一次 app metadata 更新的 RFC 3339 timestamp。

installationRedirectUris 数组

OAuth 安装回调允许列表：由应用发起的安装可返回的重定向 URI，授权时需完全匹配。

namespaceSlug string

拥有该 app 的 namespace 的 slug。

description string

由 publisher 提供的应用描述。未设置时为空。

websiteUrl string

发布者网站。未设置时为空。

defaultScopes 数组

安装应用时提供的默认作用域，以目录作用域字符串形式表示。
curl --request POST \  --url 'https://api.cursor.com/v1/origin/namespaces/NAMESPACE_SLUG/apps' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "displayName": "CI Status Bot",  "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAv7wFoV1bC9yKq3nZ8dQmXh5uJb2tR4sEwG6aP0iN8kY=\n-----END PUBLIC KEY-----",  "webhookUrl": "https://ci.acme.dev/webhooks/origin",  "events": [    "pull_request.created",    "pull_request.merged"  ],  "description": "Posts CI status on pull requests.",  "websiteUrl": "https://ci.acme.dev",  "installationRedirectUris": [    "https://ci.acme.dev/origin/setup"  ],  "defaultScopes": [    "repository:contents:read",    "repository:pull_requests:read"  ]}'

响应结构：

{  "id": "app_01k2ja2000e0080000000000a1",  "displayName": "CI Status Bot",  "webhookUrl": "https://ci.acme.dev/webhooks/origin",  "events": [    "pull_request.created",    "pull_request.merged"  ],  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-01T09:30:00Z",  "installationRedirectUris": [    "https://ci.acme.dev/origin/setup"  ],  "namespaceSlug": "acme",  "description": "Posts CI status on pull requests.",  "websiteUrl": "https://ci.acme.dev",  "defaultScopes": [    "repository:contents:read",    "repository:pull_requests:read"  ]}

代码仓库

cloneUrl 是仅输出的 HTTPS 克隆 URL。Get Repo 会返回 cloneUrl。

合作伙伴可通过 列出应用安装可访问的代码仓库 查找其代码仓库。合作伙伴 API 不支持按命名空间列出或创建代码仓库。

列出仓库

GET/v1/origin/repos/{ownerSlug}
Scopenamespace:repositories:readAuthUser access token

列出指定所有者实体下的仓库。

路径参数

ownerSlug string 必填

父级所有者实体的 slug。

查询参数

pageSize integer

返回的最大仓库数。未设置或为 0 时默认为 30。超过 100 的值将被限制为 100。

pageToken string

来自先前响应的 next_page_token 的不透明游标。第一页为空。

filter string

可选的、不区分大小写的子字符串过滤器。

响应字段

repositories array

属于请求的所有者的仓库。

repositories[].id string

源仓库标识符。

repositories[].name string

仓库在其所属者名下的名称。

repositories[].fullName string

所有者和仓库的组合名称，例如 acme/api。

repositories[].owner object

仓库的所有者引用。

repositories[].owner.slug string

用于在 URL 中与所有者 ID 一起标识代码仓库所有者的面向 URL 的所有者 slug。

repositories[].owner.id string

源站所有者标识符。

repositories[].owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

repositories[].defaultBranch string

代码仓库默认分支的名称。

repositories[].createdAt string

RFC 3339 仓库创建时间戳。

repositories[].updatedAt string

RFC 3339 格式的仓库更新时间戳。

repositories[].pushedAt string

完整仓库响应中显示的最近一次推送的 RFC 3339 时间戳。

repositories[].cloneUrl string

仅用于输出的 HTTPS 克隆 URL；get-repository 响应中包含它。

repositories[].mirror 对象

镜像元数据。原生仓库无此字段，镜像在完成首次同步之前亦无此字段。

repositories[].mirror.source string

镜像源。允许的值：github。

repositories[].mirror.sourceId string

源端分配的不透明仓库标识符。

repositories[].mirror.status string

过渡期间生效的镜像方向，直到切换完成。允许的值：inbound、outbound。

repositories[].visibility string

代码仓库可见性。允许的值：internal、private。

repositories[].allowMergeCommit boolean

PR 是否可以以合并提交的方式合入。

repositories[].allowSquashMerge boolean

PR 是否可以通过 squash 合并方式合入。

repositories[].deleteBranchOnMerge boolean

合并时是否自动删除 head 分支。

nextPageToken string

下一页的不透明游标；当没有更多页面时为空。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "repositories": [    {      "id": "repo_01k2ja2000e0080000000000q4",      "name": "rocket",      "fullName": "acme/rocket",      "owner": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      },      "defaultBranch": "main",      "createdAt": "2026-08-01T09:30:00Z",      "updatedAt": "2026-08-02T14:45:00Z",      "pushedAt": "2026-08-02T14:45:00Z",      "cloneUrl": "https://origin.cursor.com/git/acme/rocket.git"    }  ]}

Get Repo

GET/v1/origin/repos/{ownerSlug}/{repoName}
Scoperepository:metadata:readAuthInstallation tokenUser access token

根据 (owner_id, name) 标识符返回单个仓库。

cloneUrl 是仅输出的 HTTPS 克隆 URL。Get repository 会包含 cloneUrl。

路径参数

ownerSlug 字符串 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

响应字段

id string

原始仓库标识符。

name string

该所有者名下的仓库名称。

fullName string

所有者与仓库名称的组合，例如 acme/api。

owner object

仓库的所有者引用。

owner.slug string

用于 URL 的所有者 slug，与所有者 ID 一起用于标识仓库所有者。

owner.id string

Origin 所有者标识符。

owner.type string

所有者命名空间类型。仅限输出。允许的值：team、user。未知时省略。

defaultBranch string

仓库默认分支名称。

createdAt string

RFC 3339 格式的仓库创建时间戳。

updatedAt string

RFC 3339 格式的仓库更新时间戳。

pushedAt string

完整仓库响应中显示的最近一次推送的 RFC 3339 时间戳。

cloneUrl string

仅用于输出的 HTTPS 克隆 URL；get-repository 响应包含它。

mirror 对象

镜像元数据。对于原生仓库以及镜像完成初始同步之前，此字段不存在。

mirror.source string

镜像源。允许的值：github。

mirror.sourceId string

由来源分配的不透明仓库标识符。

mirror.status string

迁移期间实际生效的镜像方向，直到切换完成。允许的值：inbound、outbound。

visibility string

代码仓库可见性。允许的值：internal、private。

allowMergeCommit boolean

PR 是否可以以合并提交的方式合入。

allowSquashMerge boolean

PR 是否可以通过 squash merge 方式合入。

deleteBranchOnMerge boolean

合并时是否自动删除 head 分支。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "id": "repo_01k2ja2000e0080000000000q4",  "name": "rocket",  "fullName": "acme/rocket",  "owner": {    "slug": "acme",    "id": "ns_01k2ja2000e0080000000000p3",    "type": "team"  },  "defaultBranch": "main",  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z",  "pushedAt": "2026-08-02T14:45:00Z",  "cloneUrl": "https://origin.cursor.com/git/acme/rocket.git"}

更新仓库

PATCH/v1/origin/repos/{ownerSlug}/{repoName}
Scoperepository:settings:writeAuthInstallation tokenUser access token

更新代码仓库设置。省略的字段保持不变，且至少须提供一个可设置的字段。

设置按固定顺序以独立群组的形式生效：默认分支、自动删除 head 分支、可见性，最后是合并方式。跨群组的更新不是原子操作。当某个群组被拒绝时，排在它之前的群组已经生效且会保持生效，因此请修正被拒绝的群组后重试，以收敛到你期望的状态。响应返回的代码仓库状态为最后一个成功生效的群组应用之后的状态。

未设置任何字段的请求将返回 InvalidArgument (HTTP 400) 。对默认分支的并发修改将返回 409 Conflict。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

请求体

defaultBranch string

新的默认分支。必须指定一个现有分支。仅支持既不从上游源拉取也不向上游源推送的仓库；其他仓库将返回 FailedPrecondition (HTTP 400) 。

allowMergeCommit boolean

PR 是否可通过合并提交合入。必须与 allowSquashMerge 一同发送，且两者中至少有一个必须为 true。若只发送其中一个，将返回 InvalidArgument (HTTP 400) 。

allowSquashMerge boolean

PR 是否可以通过 squash merge 方式合入。必须与 allowMergeCommit 一同发送，且两者中至少有一个为 true。仅发送其中一个会返回 InvalidArgument (HTTP 400) 。

deleteBranchOnMerge boolean

merge 时是否自动删除 head 分支。仅支持 PR 托管在此 API 上的仓库；若代码仓库是从上游源 pull 的，则返回 FailedPrecondition (HTTP 400) 。

visibility string

新的代码仓库可见性。可选值：internal、private。省略此项则保持可见性不变。

响应字段

id string

Origin 代码仓库标识符。

name string

代码仓库在其所有者下的名称。

fullName string

owner 与代码仓库名称的组合，例如 acme/api。

owner 对象

仓库的所有者引用。

owner.slug string

与所有者 ID 配合使用，用于识别代码仓库所有者的 URL 所有者 slug。

owner.id string

Origin owner 标识符。

owner.type string

所有者 namespace 的类型。仅输出。允许的值：team、user。未知时省略。

defaultBranch string

代码仓库的默认分支名称。

createdAt string

RFC 3339 格式的代码仓库创建时间戳。

updatedAt string

RFC 3339 格式的代码仓库更新时间戳。

pushedAt string

完整代码仓库响应中返回的最近一次推送的 RFC 3339 时间戳。

cloneUrl string

仅供输出的 HTTPS 克隆 URL；get-repository 响应中包含此项。

mirror 对象

镜像元数据。native 代码仓库不包含此字段；镜像的初始同步就绪之前也不会返回。

mirror.source string

镜像来源。允许的值：github。

mirror.sourceId string

由来源分配的不透明代码仓库标识符。

mirror.status string

过渡期间 (直到切换完成) 实际生效的镜像方向。允许的值：inbound、outbound。

visibility string

代码仓库可见性。可选值：internal、private。

allowMergeCommit boolean

PR 是否可以以合并提交的方式合入。

allowSquashMerge boolean

PR 是否可以通过压缩合并 (squash merge) 的方式合入。

deleteBranchOnMerge boolean

merge 时是否自动删除 head 分支。
curl --request PATCH \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "defaultBranch": "main",  "allowMergeCommit": false,  "allowSquashMerge": true,  "deleteBranchOnMerge": true,  "visibility": "private"}'

响应结构：

{  "id": "repo_01k2ja2000e0080000000000q4",  "name": "rocket",  "fullName": "acme/rocket",  "owner": {    "slug": "acme",    "id": "ns_01k2ja2000e0080000000000p3",    "type": "team"  },  "defaultBranch": "main",  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z",  "pushedAt": "2026-08-02T14:45:00Z",  "cloneUrl": "https://origin.cursor.com/git/acme/rocket.git",  "visibility": "private",  "allowMergeCommit": false,  "allowSquashMerge": true,  "deleteBranchOnMerge": true}

创建仓库

POST/v1/origin/repos/{ownerSlug}
Scopenamespace:repositories:createAuthUser access token

为指定所有者创建仓库。

发起请求时，所有者必须具备向 Origin 写入的资格。用户所有者必须使用 Pro、Pro Student、Pro+、Ultra 或 Start 方案。团队所有者必须拥有生效的付费团队方案，且不得处于隐私模式 (旧版) ，也不得被团队管理员关闭 Origin。若所有者不具备资格，则返回 FailedPrecondition (HTTP 400) 。读取已有仓库不受此要求限制。

代码仓库名称以不区分大小写的方式被占用。若某个名称仅在大小写上与该所有者已有的仓库不同，则会被拒绝，因此 widgets 和 Widgets 不能共存于同一命名空间。你提交的名称将按原样存储。

向新仓库的首次推送可能会重新指定其默认分支。当该次推送仅创建分支且这些分支中没有任何一个是仓库已存储的默认分支时，Origin 会将默认分支设为所创建的分支；如果该推送创建了多个分支且其中包含 main 或 master，则设为 main 或 master。其他情况下默认分支保持不变。可通过 Get Repo 读取当前值。

路径参数

ownerSlug string 必填

父级所有者实体的 slug。

请求体

name string 必填

仓库名称，在其所有者下唯一。创建时必填。

defaultBranch string

默认分支名称。响应中始终会设置。创建时，省略此字段或将其留空则默认为 "main"。

响应字段

id string

Origin 仓库标识符。

name string

所属者下的仓库名称。

fullName string

所有者和仓库名称的组合，例如 acme/api。

owner object

仓库的所有者引用。

owner.slug string

用于 URL 的所有者 slug，与所有者 ID 一起用于标识仓库所有者。

owner.id string

Origin 所有者标识符。

owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

defaultBranch string

仓库的默认分支名称。

createdAt string

RFC 3339 格式的仓库创建时间戳。

updatedAt string

RFC 3339 格式的仓库更新时间戳。

pushedAt string

完整仓库响应中显示的最近一次推送的 RFC 3339 时间戳。

cloneUrl string

仅输出的 HTTPS 克隆 URL；get-repository 响应中包含它。

mirror object

镜像元数据。原生仓库不包含此字段；镜像初始同步准备好之前亦不包含。

mirror.source string

镜像源。允许的值：github。

mirror.sourceId string

由来源分配的不透明仓库标识符。

mirror.status string

迁移期间生效的镜像方向，直到切换完成。允许的值：inbound、outbound。

visibility string

代码仓库可见性。允许的值：internal、private。

allowMergeCommit boolean

PR 是否可以以合并提交的方式合入。

allowSquashMerge boolean

PR 是否可以通过 squash 合并方式合入。

deleteBranchOnMerge boolean

合并时是否自动删除 head 分支。
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": "rocket",  "defaultBranch": "main"}'

响应结构：

{  "id": "repo_01k2ja2000e0080000000000q4",  "name": "rocket",  "fullName": "acme/rocket",  "owner": {    "slug": "acme",    "id": "ns_01k2ja2000e0080000000000p3",    "type": "team"  },  "defaultBranch": "main",  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z",  "pushedAt": "2026-08-02T14:45:00Z",  "cloneUrl": "https://origin.cursor.com/git/acme/rocket.git"}

列出分支

GET/v1/origin/repos/{ownerSlug}/{repoName}/branches
Scoperepository:contents:readAuthInstallation tokenUser access token

按名称升序列出仓库的分支及其最新提交，使用 page_size 和 page_token 分页。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

查询参数

pageSize integer

返回的最大分支数。未设置或设为 0 时，默认值为 30。超过 100 的值将按 100 处理。

pageToken string

来自先前响应中 next_page_token 的不透明游标。第一页为空。该值编码了页面偏移量，因此提供 token 时，会忽略后续请求中的 page_size。

响应字段

branches array

包含分支名称和最新提交 SHA 的分页分支记录。

branches[].name string

分支名称。

branches[].commit object

分支最新提交。

branches[].commit.sha string

分支最新提交的完整十六进制 SHA。

nextPageToken string

下一页的不透明游标；没有更多页面时为空。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/branches' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

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

获取代码仓库 Tarball

GET/v1/origin/repos/{ownerSlug}/{repoName}/tarball/{ref}
Scoperepository:contents:readAuthInstallation tokenUser access token

下载代码仓库在 ref 对应树的 gzip 压缩 tar 包。

Origin 按代码仓库和 ref 解析到的提交索引归档文件。针对某个提交的首次请求会返回 200，Content-Type: application/gzip，并将归档文件作为响应体流式传输。后续针对同一提交的请求会返回 302，响应体为空，且 Location 中包含有效期为 15 分钟的签名下载 URL；请跟随重定向获取数据。归档条目位于 tar 包根目录，不含外层目录。空代码仓库返回 ABORTED (HTTP 409 Conflict) ，无法解析的引用返回 404。

如果引用包含 "/"，请将其作为查询参数而非路径段发送：GET /v1/origin/repos/{ownerSlug}/{repoName}/tarball?ref=refs/heads/main。省略该参数将归档代码仓库的默认分支。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

代码仓库名称，在所有者实体内唯一。

ref string 必填

提交 SHA (完整或缩写的十六进制) 、不带前缀的分支或标签名称、完全限定的 refs/heads/... 或 refs/tags/...，或符号引用 HEAD。不支持 glob 或 revspec，因此会拒绝 <rev>~3。为空时使用代码仓库默认分支。

响应字段

sha string

解析后的提交对象 ID：40 或 64 个字符的十六进制值。返回给 Connect 和 JSON 调用方；通过 REST 时，请从归档文件名或签名 URL 中读取。

downloadUrl string

有效期为 15 分钟的短期签名下载 URL。响应直接流式传输归档文件时为空，即针对该代码仓库和提交的首次请求。通过 REST 时，同一 URL 会作为 302 的 Location 请求头发送。
curl --request GET --location --output repo.tar.gz \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/tarball/HEAD' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "downloadUrl": "https://artifacts.origin.cursor.com/tarballs/0192f7a4-6c1e-7b3a-9f21-3d54c9a7e6b0/9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4.tar.gz?Expires=1767225600&Signature=EXAMPLE&Key-Pair-Id=KEXAMPLE123",  "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4"}

同步镜像

POST/v1/origin/repos/{ownerSlug}/{repoName}:syncMirror
Scoperepository:contents:readAuthInstallation tokenUser access token

将镜像代码仓库的一个引用与其上游源同步。同步目标达成时返回 HTTP 200，同步仍在进行时返回 HTTP 202。wait=false (默认值) 会安排同步，通常返回 202；如果可从 ref 访问到 sha，则会立即返回 200。wait=true 会阻塞至同步完成或等待时限 (约 2 分钟) 到期；到期后仍会返回 202，同步将在后台继续。不从上游源拉取的代码仓库将被拒绝。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

在所有者实体内唯一的仓库名称。

请求体

ref string 必填

要获取的完整 Git 引用名称。必须以 refs/ 开头，且该前缀后必须指定引用，例如 refs/heads/main 或 refs/tags/v1。main 等短名称会被拒绝，并返回 INVALID_ARGUMENT。

wait boolean

设为 true 时，会阻塞至同步完成或等待时限到期。默认值为 false。

sha string

可选的完整提交对象 ID：40 或 64 个十六进制字符。省略或留空则等待 ref 的最新提交。设置后，如果可从 ref 访问到该值，调用会提前返回，无需等待其他镜像任务完成。其他值会被拒绝，并返回 INVALID_ARGUMENT。

响应字段

synced boolean

已知同步目标已达成时为 true；同步仍在等待时为 false。该字段始终存在，与 HTTP 状态码对应：true 时为 200，false 时为 202。
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}'

响应结构：

{  "synced": true}

镜像转换端点的文档位于 Origin Migration API。同步镜像 仍保留在本页面。

分离代码仓库镜像

参见 Detach 代码仓库镜像。

获取镜像转换作业

参见 获取镜像转换作业。

获取活跃的镜像转换作业

参见 Get Active 镜像转换作业。

强制代码仓库镜像切换

参见强制代码仓库镜像切换。

转换代码仓库镜像

参见转换代码仓库镜像。

检查

  • 首次执行更新或插入操作时，会自动创建相应的检查套件。
  • 必需检查会与安装该应用的应用以及套件 key 匹配，也可选择与运行 key 匹配。name 仅用于显示，不参与匹配。
  • 请在多次尝试中保持 key 值稳定且易于用户理解，因为必需检查的配置以它们为键。
  • 重用 externalId 可更新一次尝试，这会丢弃该尝试之前的结果；重试时请使用新的 externalId，以便将较早的尝试保留为历史记录。
  • 使用 checkRun.output 提供用户可读的结果：
    • title：简短的结果标题，最多 255 个字符。
    • summary：主要的 Markdown 摘要，最多 65,535 个 UTF-8 字节。
    • text：扩展的 Markdown 详细信息，最多 65,535 个 UTF-8 字节。
  • 使用 detailsUrl 链接到提供方的外部结果页面。

创建检查运行

POST/v1/origin/repos/{ownerSlug}/{repoName}/check-runs
Scoperepository:checks:writeAuthInstallation token

使用具有 repository:checks:write 权限的安装访问令牌对检查套件和检查运行执行 upsert 操作。写入操作归属于拥有已认证安装的应用。使用相同的 (repo, head_sha, suite.key, check.key) 重复调用时，会就地更新现有的检查运行，而不会创建重复项。

该端点以原子方式解析或创建测试套件尝试记录，并对一次运行尝试执行 upsert (更新或插入) 。externalUpdatedAt 用于对同一运行标识的更新进行排序；过时的重试不会覆盖较新的状态。

deadlineAt 记录运行的可选截止时间。Origin 会存储该值、在读取时返回，并在运行变为 completed 时将其清除。超过当前时间 24 小时的截止时间不会被截断，而是以 InvalidArgument (HTTP 400) 拒绝。

当某个仍处于 in_progress 的运行超过截止时间时，Origin 会自行以 timed_out 结论完成该运行，并发送 repository.check_run.completed。过期处理作为周期性扫描运行，而不是基于每个运行的定时器，因此运行可能在超过截止时间后短暂停留，随后才被 Origin 关闭。处于 queued 状态的运行永不过期，未包含 deadlineAt 的运行也不会过期。在截止时间之前自行完成该运行即可清除其截止状态。Origin 在将运行判定为超时时不会更改该运行的 externalUpdatedAt，因此来自你的提供者的后续完成仍然可以覆盖 timed_out 结论。

路径参数

ownerSlug 字符串 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体中唯一。

请求体

headSha string 必填

该检查运行所针对的最新提交的 SHA (40 或 64 位十六进制) 。

checkSuite 对象 必填

该检查运行所属的套件；随该检查运行一起被插入或更新。

checkSuite.key 字符串 必填

由应用选择的稳定键，用于在多次尝试中标识逻辑套件。

checkSuite.name string 必填

面向用户的套件名称。

checkSuite.detailsUrl string

可选链接，指向有关整个套件的更多详细信息。

checkSuite.externalId string 必填

提供者为此测试套件尝试分配的不可变标识。

checkRun 对象 必填

要更新或插入的检查运行。

checkRun.key string 必填

由应用选择的稳定键，用于在多次尝试中标识相同的逻辑检查。

checkRun.name string 必填

面向用户的 check-run 名称。

checkRun.status string 必填

可设置的值：CHECK_RUN_LIFECYCLE_STATUS_UNSPECIFIED、queued、in_progress、completed。schema 中还列出了 rerequested，该值仅由 Origin 在重新请求时设置；携带该值的请求会返回 InvalidArgument (HTTP 400) 。

checkRun.conclusion string

当且仅当 status == completed 时为必填。允许的值：CHECK_RUN_CONCLUSION_UNSPECIFIED、success、failure、neutral、cancelled、skipped、timed_out、action_required、stale。

checkRun.externalUpdatedAt string 必填

外部系统的最后更新时间。用于对并发更新进行排序，以防过时的重试覆盖较新的状态。

checkRun.startedAt string

检查运行开始的时间。

checkRun.completedAt string

检查运行何时完成。

checkRun.detailsUrl string

可选链接，指向有关此特定检查运行的更多详细信息 (例如提供者的作业/构建 URL) 。

checkRun.externalId string 必填

提供方为此次检查分配的不可变标识。

checkRun.output 对象

此检查运行的可读输出。

checkRun.output.title string

输出内容的简短标题。最大长度：255 个字符。

checkRun.output.summary string

输出摘要。可包含 Markdown。最大 UTF-8 大小：65535 字节。

checkRun.output.text string

详细输出。可包含 Markdown。最大 UTF-8 大小：65535 字节。

checkRun.deadlineAt string

该检查运行的截止时间，采用 RFC 3339 时间戳格式。超出当前时间 24 小时以上的值不会被截断，而是返回 InvalidArgument (HTTP 400) 予以拒绝。创建时省略此字段表示不记录截止时间；更新时省略此字段则保持已存储的截止时间不变。

checkRun.isRerequestable boolean

声明该运行可按请求重新运行。将其设为 true 即表示你的应用承诺订阅 repository.check_run.rerequested，并在每次投递时作出响应，方法是为相同的 head SHA 和 key 发布一条新的运行：要么使用新的 externalId 创建新运行，将旧的尝试保留为历史记录；要么使用相同的 externalId 更新被重新请求的运行，就地刷新该运行。在该新发布到达之前，被重新请求的运行在提交的最新检查状态中将显示为待处理，因此必需的检查会阻止合并，PR 会显示该运行正等待其重运行；声明可重新请求但不作出响应会使该检查处于搁置状态。你发布时，Origin 不会验证该订阅。省略此字段可保留已存储的值 (新运行默认为 false) ；发送 false 可撤回该声明。

响应字段

checkSuite 对象

已插入或更新的检查套件。

checkSuite.id string

由服务器分配的检查套件标识符。

checkSuite.repository 对象

套件的仓库引用。

checkSuite.repository.id string

容器引用中的存储库标识符。

checkSuite.repository.name string

容器引用中的仓库名称。

checkSuite.repository.owner 对象

仓库的所有者引用。

checkSuite.repository.owner.slug string

与所有者 ID 一起用于识别仓库所有者的面向 URL 的所有者 slug。

checkSuite.repository.owner.id string

Origin 所有者标识符。

checkSuite.repository.owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

checkSuite.sha string

套件关联的提交 SHA。

checkSuite.key string

由应用选择的稳定必需检查标识。必需检查根据应用和此键匹配，而不是名称。

checkSuite.name string

仅供显示的套件名称；不用于必填项检查匹配。

checkSuite.detailsUrl string

可选：指向提供者套件级结果的链接。

checkSuite.createdAt string

RFC 3339 套件创建时间戳。

checkSuite.updatedAt string

最新测试套件更新的 RFC 3339 时间戳。

checkSuite.externalId string

此测试套件尝试的提供者身份。

checkSuite.actor 对象

生成该套件的公共参与者。

checkSuite.actor.user 对象

操作主体的用户变体。用户执行该操作时设置。

checkSuite.actor.user.id string

用户的公开标识符。

checkSuite.actor.user.email string

用户的电子邮件地址。存在 user 变体时该值必定会设置。

checkSuite.actor.user.displayName string

用户显示名称：账户的名字和姓氏以空格连接，与产品中呈现的名称相同。若账户没有名称则省略。

checkSuite.actor.user.handle string

用户已认领的个人资料用户名，不含 @ 前缀。仅在该资料公开可见时提供；否则省略。

checkSuite.actor.app 对象

操作主体的应用变体。在应用执行该操作时设置。

checkSuite.actor.app.id string

应用的公开标识符。

checkSuite.actor.app.displayName string

应用注册的显示名称。若应用无法解析或在 Cursor 的第一方托管主体上，则省略此字段。

checkSuite.actor.serviceAccount 对象

actor 的服务账户变体。当操作由服务账户执行时设置。

checkSuite.actor.serviceAccount.id string

服务账户的公共标识符。

checkRun 对象

已上载或已更新的检查运行。

checkRun.id string

服务器分配的检查运行标识符。

checkRun.repository 对象

运行的仓库引用。

checkRun.repository.id string

容器引用中的存储库标识符。

checkRun.repository.name string

容器引用中的仓库名称。

checkRun.repository.owner 对象

仓库的所有者引用。

checkRun.repository.owner.slug string

与所有者 ID 一起用于识别仓库所有者的面向 URL 的所有者 slug。

checkRun.repository.owner.id string

Origin 所有者标识符。

checkRun.repository.owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

checkRun.checkSuite 对象

对所属检查套件的引用。

checkRun.checkSuite.id string

所属检查套件的服务器分配标识符。

checkRun.sha string

运行关联的提交 SHA。

checkRun.key string

由应用选择的稳定逻辑运行标识；所需的检查可基于应用、suite 键以及此键匹配。

checkRun.name string

仅供显示的运行名称；不用于必需检查匹配。

checkRun.status string

生命周期状态：queued、in_progress、completed 或 rerequested。rerequested 指已完成的运行被请求重新运行，而拥有该运行的应用尚未作出响应：应将其视为待处理，并按 queued 的方式呈现。

checkRun.conclusion string

在运行已完成或被重新请求时返回；取值可为 success、failure、neutral、cancelled、skipped、timed_out、action_required 或 stale。对于被重新请求的运行，该值是已被取代的那次尝试的结论，因此仅在 status 为 completed 时读取。

checkRun.detailsUrl string

指向提供商完整结果页面的独立链接。

checkRun.externalUpdatedAt string

用于对更新进行排序的外部更新时间戳，以防过时的重试替换较新的状态。

checkRun.startedAt string

提供方上报的 RFC 3339 开始时间 (如已提供) 。

checkRun.completedAt string

提供方上报的 RFC 3339 完成时间 (如已提供) 。

checkRun.createdAt string

运行创建时间戳 (RFC 3339 格式) 。

checkRun.updatedAt string

最近一次已持久化运行更新的 RFC 3339 时间戳。

checkRun.externalId string

单次尝试的提供者标识。要更新该尝试请复用此值；若重试请使用新的值。

checkRun.actor object

产生该运行的公共主体。

checkRun.actor.user 对象

操作主体的用户变体。用户执行该操作时设置。

checkRun.actor.user.id string

用户的公开标识符。

checkRun.actor.user.email string

用户的电子邮件地址。存在 user 变体时该值必定会设置。

checkRun.actor.user.displayName string

用户显示名称：账户的名字和姓氏以空格连接，与产品中呈现的名称相同。若账户没有名称则省略。

checkRun.actor.user.handle string

用户已认领的个人资料用户名，不含 @ 前缀。仅在该资料公开可见时提供；否则省略。

checkRun.actor.app 对象

操作主体的应用变体。在应用执行该操作时设置。

checkRun.actor.app.id string

应用的公开标识符。

checkRun.actor.app.displayName string

应用注册的显示名称。当应用无法解析或在 Cursor 的第一方托管主体上时省略。

checkRun.actor.serviceAccount 对象

actor 的服务账户变体。当操作由服务账户执行时设置。

checkRun.actor.serviceAccount.id string

服务账户的公共标识符。

checkRun.output 对象

供人阅读的结果对象，包含标题、摘要，以及 (如提供) 更长的文本。

checkRun.output.title string

输出内容的简短标题。最大长度：255 个字符。

checkRun.output.summary string

输出摘要。可包含 Markdown。最大 UTF-8 大小：65535 字节。

checkRun.output.text string

详细输出。可包含 Markdown。最大 UTF-8 大小：65535 字节。

checkRun.deadlineAt string

为该检查运行记录的截止时间，采用 RFC 3339 时间戳格式。当运行没有截止时间时 (包括运行完成后) ，不返回该字段。

checkRun.isRerequestable boolean

上报的应用是否将该运行声明为可重新请求。

checkRun.rerequestedAt string

尚未处理的重新请求的时间，采用 RFC 3339 时间戳格式。没有待处理的重新请求时不返回该字段；当拥有该运行的应用再次发布时清除此字段。只要该字段被设置，status 就为 rerequested，该运行将保留在该提交的最新检查状态并显示为待处理，而 conclusion 和计时仍保留被取代的结果；因此在该应用作出响应之前，必需的检查会阻止合并。

checkRun.rerequestedBy 对象

发起重新运行的主体，包含与 actor 相同的 actor 变体。只要设置了 rerequestedAt 就会返回该字段，并随其一同清除。
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": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",  "checkSuite": {    "key": "ci-8842",    "name": "CI",    "detailsUrl": "https://ci.acme.dev/runs/8842",    "externalId": "build-8842"  },  "checkRun": {    "key": "ci-8842-unit-tests",    "name": "unit-tests",    "status": "completed",    "conclusion": "success",    "externalUpdatedAt": "2026-08-02T14:44:30Z",    "startedAt": "2026-08-02T14:40:00Z",    "completedAt": "2026-08-02T14:44:30Z",    "detailsUrl": "https://ci.acme.dev/runs/8842",    "externalId": "run-8842",    "output": {      "title": "Unit tests",      "summary": "128 tests passed.",      "text": "All suites green."    }  }}'

响应结构：

{  "checkSuite": {    "id": "crg_01k2ja2000e0080000000000h8",    "repository": {      "id": "repo_01k2ja2000e0080000000000q4",      "name": "rocket",      "owner": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      }    },    "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "key": "ci-8842",    "name": "CI",    "detailsUrl": "https://ci.acme.dev/runs/8842",    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T14:45:00Z",    "externalId": "build-8842",    "actor": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "jane@acme.dev"      }    }  },  "checkRun": {    "id": "cr_01k2ja2000e0080000000000g7",    "repository": {      "id": "repo_01k2ja2000e0080000000000q4",      "name": "rocket",      "owner": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      }    },    "checkSuite": {      "id": "crg_01k2ja2000e0080000000000h8"    },    "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "key": "ci-8842-unit-tests",    "name": "unit-tests",    "status": "completed",    "conclusion": "success",    "detailsUrl": "https://ci.acme.dev/runs/8842",    "externalUpdatedAt": "2026-08-02T14:44:30Z",    "startedAt": "2026-08-02T14:40:00Z",    "completedAt": "2026-08-02T14:44:30Z",    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T14:45:00Z",    "externalId": "run-8842",    "actor": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "jane@acme.dev"      }    },    "output": {      "title": "Unit tests",      "summary": "128 tests passed.",      "text": "All suites green."    }  }}

批量更新或插入检查运行

POST/v1/origin/repos/{ownerSlug}/{repoName}/check-runs:batchUpsert
Scoperepository:checks:writeAuthInstallation token

以原子方式对属于同一测试套件的多个检查运行执行 upsert 操作。该请求最多接受 10 个运行，并拒绝重复的 (external_id, key) 标识。要么所有运行全部提交，要么整个请求回滚。

每个运行均接受与 Post Check Run 相同的可选 deadlineAt。

路径参数

ownerSlug string 必填

所有者实体的唯一标识 (slug) 。

repoName string 必填

仓库名称，在所属主体范围内唯一。

请求体

headSha string 必填

检查运行所报告的头部提交 SHA (40 或 64 个十六进制字符) 。

checkSuite 对象 必填

此请求中每次检查运行共享的套件。

checkSuite.key string 必填

由应用选择的稳定键，用于在多次尝试中标识逻辑套件。

checkSuite.name string 必填

面向用户的套件名称。

checkSuite.detailsUrl string

可选链接，指向有关整个套件的更多详细信息。

checkSuite.externalId string 必填

提供方为此次测试套件运行分配的不可变标识。

checkRuns 数组 必填

按响应顺序对检查运行进行 upsert (更新或插入) 。必须包含 1 到 10 个条目，且 (external_id, key) 的组合唯一。

checkRuns[0].key string 必填

由应用选择的稳定键，用于在多次尝试中标识同一逻辑检查。

checkRuns[0].name string 必填

面向用户的检查运行名称。

checkRuns[0].status string 必填

可设置的值：CHECK_RUN_LIFECYCLE_STATUS_UNSPECIFIED、queued、in_progress、completed。schema 中还列出了 rerequested，该值仅由 Origin 在重新请求时设置；携带该值的请求会返回 InvalidArgument (HTTP 400) 。

checkRuns[0].conclusion string

仅当 status == completed 时必填。允许的值：CHECK_RUN_CONCLUSION_UNSPECIFIED、success、failure、neutral、cancelled、skipped、timed_out、action_required、stale。

checkRuns[0].externalUpdatedAt string 必填

外部系统的最后更新时间。用于对并发更新进行排序，防止过时的重试覆盖较新的状态。

checkRuns[0].startedAt string

检查运行开始的时间。

checkRuns[0].completedAt string

检查运行完成时。

checkRuns[0].detailsUrl string

指向有关此特定检查运行的更多详细信息的可选链接 (例如提供者的作业/构建 URL) 。

checkRuns[0].externalId string 必填

由提供者为此检查尝试分配的不可变身份。

checkRuns[0].output 对象

此检查运行的人类可读输出。

checkRuns[0].output.title string

输出内容的简短标题。最大长度：255 个字符。

checkRuns[0].output.summary string

输出摘要。可包含 Markdown。最大 UTF-8 大小：65535 字节。

checkRuns[0].output.text string

详细输出。可能包含 Markdown。最大 UTF-8 大小：65535 字节。

checkRuns[0].deadlineAt string

检查运行的截止时间，使用 RFC 3339 时间戳。超过未来 24 小时的值将以 InvalidArgument (HTTP 400) 被拒绝，而不是被截断。创建时省略表示不记录截止时间；更新时省略表示保持已存储的截止时间不变。

checkRuns[0].isRerequestable boolean

声明该运行可按请求重新运行。将其设为 true 即表示你的应用承诺订阅 repository.check_run.rerequested，并在每次投递时通过为相同的 head SHA 和 key 发布新的运行来响应：要么使用新的 externalId 创建新运行，从而将旧尝试保留为历史；要么使用相同的 externalId 更新被重新请求的运行，从而就地刷新它。在新的发布到达之前，被重新请求的运行在该提交的最新检查状态中会显示为待处理，因此必需的检查会阻止合并，PR 会显示该运行正在等待重新运行；声明可重新请求但不作回应会使该检查陷入搁置。你发布时，Origin 不会验证该订阅。省略此字段以保留已存储的值 (新运行默认为 false) ；发送 false 可撤回该声明。

响应字段

checkSuite 对象

所有已返回的检查运行共享的持久化套件。

checkSuite.id string

由服务器分配的检查套件标识符。

checkSuite.repository 对象

套件的仓库引用。

checkSuite.repository.id string

容器引用中的仓库标识符。

checkSuite.repository.name string

容器引用中的仓库名称。

checkSuite.repository.owner 对象

代码仓库的所有者引用。

checkSuite.repository.owner.slug string

用于 URL 的所有者 slug，与所有者 ID 一起用于标识仓库所有者。

checkSuite.repository.owner.id string

Origin 所有者标识符。

checkSuite.repository.owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

checkSuite.sha string

该测试套件所关联的提交 SHA。

checkSuite.key string

由应用选择的稳定的必需检查标识。必需检查基于应用和此密钥匹配，而非名称。

checkSuite.name string

仅供显示的套件名称；不用于必需检查匹配。

checkSuite.detailsUrl string

可选链接，指向提供者的套件级结果。

checkSuite.createdAt string

suite 创建时间戳，采用 RFC 3339 格式。

checkSuite.updatedAt string

最近套件更新的 RFC 3339 时间戳。

checkSuite.externalId string

此套件尝试的提供者身份。

checkSuite.actor 对象

生成该套件的公共实体。

checkSuite.actor.user 对象

执行者的用户变体。用户执行操作时设置。

checkSuite.actor.user.id string

用户的公开标识符。

checkSuite.actor.user.email string

用户的电子邮件地址。用户变体存在时始终设置。

checkSuite.actor.user.displayName string

用户显示名称：账户的名字和姓氏以空格连接，与产品中显示的名称相同。账户没有名称时省略。

checkSuite.actor.user.handle string

用户已认领的个人资料账户名，不含 @ 前缀。仅在该个人资料公开可见时提供；否则省略。

checkSuite.actor.app 对象

操作执行者的应用变体。应用执行该操作时设置。

checkSuite.actor.app.id string

应用的公开标识符。

checkSuite.actor.app.displayName string

应用的注册显示名称。当应用无法解析或在 Cursor 的第一方托管执行者上时省略。

checkSuite.actor.serviceAccount 对象

操作主体的服务账户变体。服务账户执行该操作时设置。

checkSuite.actor.serviceAccount.id string

服务帐户的公共标识符。

checkRuns 数组

已持久化的检查运行按请求中的顺序返回。

checkRuns[].id string

服务器分配的检查运行标识符。

checkRuns[].repository 对象

本次运行的仓库引用。

checkRuns[].repository.id string

容器引用中的仓库标识符。

checkRuns[].repository.name string

容器引用中的仓库名称。

checkRuns[].repository.owner 对象

代码仓库的所有者引用。

checkRuns[].repository.owner.slug string

与所有者 ID 一起使用的面向 URL 的所有者 slug，用于标识仓库所有者。

checkRuns[].repository.owner.id string

Origin 所有者标识符。

checkRuns[].repository.owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

checkRuns[].checkSuite 对象

对所属检查套件的引用。

checkRuns[].checkSuite.id string

所属检查套件的服务器分配标识符。

checkRuns[].sha string

运行所关联的提交 SHA。

checkRuns[].key string

由应用选择的稳定逻辑运行标识；必需的检查可能会根据应用、套件键和此键进行匹配。

checkRuns[].name string

仅供显示的运行名称；不会用于必需检查的匹配。

checkRuns[].status string

生命周期状态：queued、in_progress、completed 或 rerequested。rerequested 运行指已完成但被请求重新运行、且所属应用尚未回应的运行：应将其视为待处理，并按 queued 的方式呈现。

checkRuns[].conclusion string

在已完成或被重新请求的运行中存在；取值为 success、failure、neutral、cancelled、skipped、timed_out、action_required 或 stale。对于被重新请求的运行，它表示被取代尝试的判定，因此仅在 status 为 completed 时读取。

checkRuns[].detailsUrl string

指向提供者完整结果页面的独立链接。

checkRuns[].externalUpdatedAt string

用于对更新进行排序的外部更新时间戳，以防过时的重试替换较新的状态。

checkRuns[].startedAt string

如有提供，则为提供方上报的 RFC 3339 开始时间。

checkRuns[].completedAt string

如已提供，则为提供方报告的 RFC 3339 完成时间。

checkRuns[].createdAt string

RFC 3339 运行创建时间戳。

checkRuns[].updatedAt string

最新已持久化运行更新的 RFC 3339 时间戳。

checkRuns[].externalId string

单次尝试的提供者标识。可复用以更新该尝试；重试时请使用新的值。

checkRuns[].actor 对象

发起此次运行的公共参与者。

checkRuns[].actor.user 对象

执行者的用户变体。用户执行操作时设置。

checkRuns[].actor.user.id string

用户的公开标识符。

checkRuns[].actor.user.email string

用户的电子邮件地址。用户变体存在时始终设置。

checkRuns[].actor.user.displayName string

用户显示名称：账户的名字和姓氏以空格连接，和产品中显示的名称相同。账户没有名称时省略。

checkRuns[].actor.user.handle string

用户已认领的个人资料账户名，不含 @ 前缀。仅在该个人资料公开可见时提供；否则省略。

checkRuns[].actor.app 对象

操作执行者的应用变体。应用执行该操作时设置。

checkRuns[].actor.app.id string

应用的公开标识符。

checkRuns[].actor.app.displayName string

应用的注册显示名称。当应用无法解析或在 Cursor 的第一方托管执行者上时省略。

checkRuns[].actor.serviceAccount 对象

操作主体的服务账户变体。服务账户执行该操作时设置。

checkRuns[].actor.serviceAccount.id string

服务帐户的公共标识符。

checkRuns[].output 对象

面向人类可读的结果对象，包含标题、摘要，以及 (如提供) 更长的文本。

checkRuns[].output.title string

输出内容的简短标题。最大长度：255 个字符。

checkRuns[].output.summary string

输出摘要。可包含 Markdown。最大 UTF-8 大小：65535 字节。

checkRuns[].output.text string

详细输出。可能包含 Markdown。最大 UTF-8 大小：65535 字节。

checkRuns[].deadlineAt string

检查运行的截止时间，以 RFC 3339 时间戳记录。若该运行没有截止时间，则不提供；运行完成后亦然。

checkRuns[].isRerequestable boolean

上报的应用是否声明此运行可重新请求。

checkRuns[].rerequestedAt string

待处理的重新请求的 RFC 3339 时间戳。若没有待处理的重新请求则不提供；当拥有该运行的应用再次发布时会被清除。设置后，status 为 rerequested，该运行会保留在该提交的最新检查状态并显示为“待处理”，而 conclusion 和各时间字段仍显示被取代的结果，因此在应用回应之前，必需的检查会阻止合并。

checkRuns[].rerequestedBy 对象

请求重新运行的主体，其 actor 变体与 actor 相同。设置 rerequestedAt 时存在，并会随其一同清除。
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": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",  "checkSuite": {    "key": "ci-8842",    "name": "CI",    "detailsUrl": "https://ci.acme.dev/runs/8842",    "externalId": "build-8842"  },  "checkRuns": [    {      "key": "ci-8842-unit-tests",      "name": "unit-tests",      "status": "completed",      "conclusion": "success",      "externalUpdatedAt": "2026-08-02T14:44:30Z",      "startedAt": "2026-08-02T14:40:00Z",      "completedAt": "2026-08-02T14:44:30Z",      "detailsUrl": "https://ci.acme.dev/runs/8842",      "externalId": "run-8842",      "output": {        "title": "Unit tests",        "summary": "128 tests passed.",        "text": "All suites green."      }    }  ]}'

响应结构：

{  "checkSuite": {    "id": "crg_01k2ja2000e0080000000000h8",    "repository": {      "id": "repo_01k2ja2000e0080000000000q4",      "name": "rocket",      "owner": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      }    },    "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "key": "ci-8842",    "name": "CI",    "detailsUrl": "https://ci.acme.dev/runs/8842",    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T14:45:00Z",    "externalId": "build-8842",    "actor": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "jane@acme.dev"      }    }  },  "checkRuns": [    {      "id": "cr_01k2ja2000e0080000000000g7",      "repository": {        "id": "repo_01k2ja2000e0080000000000q4",        "name": "rocket",        "owner": {          "slug": "acme",          "id": "ns_01k2ja2000e0080000000000p3",          "type": "team"        }      },      "checkSuite": {        "id": "crg_01k2ja2000e0080000000000h8"      },      "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",      "key": "ci-8842-unit-tests",      "name": "unit-tests",      "status": "completed",      "conclusion": "success",      "detailsUrl": "https://ci.acme.dev/runs/8842",      "externalUpdatedAt": "2026-08-02T14:44:30Z",      "startedAt": "2026-08-02T14:40:00Z",      "completedAt": "2026-08-02T14:44:30Z",      "createdAt": "2026-08-01T09:30:00Z",      "updatedAt": "2026-08-02T14:45:00Z",      "externalId": "run-8842",      "actor": {        "user": {          "id": "user_01k2ja2000e0080000000000c3",          "email": "jane@acme.dev"        }      },      "output": {        "title": "Unit tests",        "summary": "128 tests passed.",        "text": "All suites green."      }    }  ]}

获取检查运行

GET/v1/origin/repos/{ownerSlug}/{repoName}/check-runs/{checkRunId}
Scoperepository:checks:readAuthInstallation tokenUser access token

按服务器分配的 ID (cr_...) 返回单个检查运行。

路径参数

ownerSlug 字符串 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体范围内唯一。

checkRunId string 必填

服务器分配的检查运行 ID (cr_...) 。

响应字段

id string

服务器分配的检查运行标识符。

repository 对象

运行所用的代码仓库引用。

repository.id string

容器引用中的存储库标识符。

repository.name string

容器引用中的仓库名称。

repository.owner 对象

仓库的所有者引用。

repository.owner.slug string

面向 URL 的所有者 slug，与所有者 ID 配合使用，用于标识代码仓库的所有者。

repository.owner.id string

源所有者标识符。

repository.owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

checkSuite 对象

对所属检查套件的引用。

checkSuite.id 字符串

所属检查套件的服务器分配标识符。

sha string

运行关联的提交 SHA。

key string

由应用选择的稳定逻辑运行标识；必需的检查可根据应用、套件键和此键进行匹配。

name string

仅用于显示的运行名称；不会用于必需检查匹配。

status string

生命周期状态：queued、in_progress、completed 或 rerequested。rerequested 运行是指已完成、已被请求重新运行但所属 app 尚未响应的运行：应将其视为待处理，并按 queued 的方式呈现。

conclusion string

此字段在已完成或已重新请求的运行中存在：success、failure、neutral、cancelled、skipped、timed_out、action_required 或 stale。对于已重新请求的运行，它表示被取代尝试的裁决，因此仅在 status 为 completed 时读取。

detailsUrl string

指向提供方完整结果页面的单独链接。

externalUpdatedAt string

外部更新时间戳，用于对更新进行排序，防止过时的重试替换较新的状态。

startedAt string

提供方报告的 RFC 3339 开始时间 (如有提供) 。

completedAt string

提供方报告的 RFC 3339 完成时间 (如已提供) 。

createdAt string

运行创建时间戳 (RFC 3339) 。

updatedAt string

最新已持久化运行更新的 RFC 3339 时间戳。

externalId string

单次尝试的提供者标识。重复使用该值可更新该次尝试；重试时请使用新值。

actor 对象

生成此运行的公共参与者。

actor.user 对象

操作主体的用户变体。用户执行该操作时设置。

actor.user.id string

用户的公开标识符。

actor.user.email string

用户的电子邮件地址。在存在 user 变体时始终设置。

actor.user.displayName string

用户的显示名称：账户的名字与姓氏以空格连接，产品显示的即为此名称。若账户没有名称则省略。

actor.user.handle string

用户已认领的个人资料用户名，不含 @ 前缀。仅在该个人资料公开可见时提供；否则省略。

actor.app 对象

操作主体的应用 (app) 变体。在应用执行该操作时设置。

actor.app.id string

应用的公开标识符。

actor.app.displayName string

应用已注册的显示名称。当应用无法解析或在 Cursor 的第一方托管主体上时省略。

actor.serviceAccount 对象

操作主体的服务账户变体。在服务账户执行该操作时设置。

actor.serviceAccount.id string

服务账户的公开标识符。

output 对象

供人阅读的结果对象，包含标题、摘要，以及在提供时的更长文本。

output.title string

输出的简短标题。最大长度：255 个字符。

output.summary string

输出摘要。可包含 Markdown。最大 UTF-8 大小：65535 字节。

output.text string

详细输出。可能包含 Markdown。最大 UTF-8 大小：65535 字节。

deadlineAt string

以 RFC 3339 时间戳记录的检查运行截止时间。运行未设置截止时间时不返回此字段，运行完成后亦不返回。

isRerequestable boolean

报告该运行的 app 是否将其声明为可重新请求。

rerequestedAt string

未处理的重新请求的 RFC 3339 时间戳。没有待处理的重新请求时不返回此字段；当拥有该运行的 app 再次发布时清除。该字段已设置期间，status 为 rerequested，此运行仍保留在该提交的最新检查状态中，并显示为待处理，而 conclusion 和各时间字段仍携带已被取代的结果；因此在该 app 作出响应之前，必需的检查会阻止合并。

rerequestedBy 对象

请求重新运行的主体，携带与 actor 相同的 actor 变体。只要设置了 rerequestedAt 即存在，并随其一起清除。
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'

响应结构：

{  "id": "cr_01k2ja2000e0080000000000g7",  "repository": {    "id": "repo_01k2ja2000e0080000000000q4",    "name": "rocket",    "owner": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    }  },  "checkSuite": {    "id": "crg_01k2ja2000e0080000000000h8"  },  "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",  "key": "ci-8842-unit-tests",  "name": "unit-tests",  "status": "completed",  "conclusion": "success",  "detailsUrl": "https://ci.acme.dev/runs/8842",  "externalUpdatedAt": "2026-08-02T14:44:30Z",  "startedAt": "2026-08-02T14:40:00Z",  "completedAt": "2026-08-02T14:44:30Z",  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z",  "externalId": "run-8842",  "actor": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  },  "output": {    "title": "Unit tests",    "summary": "128 tests passed.",    "text": "All suites green."  }}

列表检查运行注解

GET/v1/origin/repos/{ownerSlug}/{repoName}/check-runs/{checkRunId}/annotations
Scoperepository:checks:readAuthInstallation tokenUser access token

按 ID 升序列出检查运行的注释。

注释 ID 可按时间排序，因此 ID 升序即为创建顺序。page token 会为后续整个序列固定分页大小和范围，因此一旦传入 page token，pageSize 即被忽略。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体中唯一。

checkRunId string 必填

服务器分配的 check run ID。

查询参数

pageSize 整数

返回的注释数量上限。省略或设为零时，默认值为 30；超过 100 的值将被限制为 100。

pageToken string

来自上一次响应的 nextPageToken 的不透明游标。第一页可省略。

响应字段

annotations array

注释的分页结果，按 ID 升序排列。

annotations[].id string

稳定的 Origin 注释 ID。ID 可按时间排序。

annotations[].checkRunId string

此注释所属的检查运行的 ID。

annotations[].annotationLevel string

注解的严重级别。允许的值：notice、warning、failure。

annotations[].message string

注释消息。

annotations[].title string

注释标题。注释不存在时不显示。

annotations[].rawDetails string

raw 详情文本。若该注解没有此内容，则不存在该字段。

annotations[].createdAt string

该注释的创建时间 (RFC 3339) 。

annotations[].updatedAt string

注释的最后更新时间 (RFC 3339) 。

annotations[].location object

源位置。运行级注释中不提供此项。

annotations[].location.path string

规范的相对于代码仓库的文件路径。

annotations[].location.startLine 整数

范围的起始行。从 1 开始计数，且包含该行。

annotations[].location.endLine 整数

范围的结束行。从 1 开始计数，且包含该行。

annotations[].location.columns 对象

列范围。仅当注释覆盖单行时才出现。

annotations[].location.columns.startColumn 整数

范围的起始列。从 1 开始计数，且包含该列。

annotations[].location.columns.endColumn 整数

范围的最后一列。从 1 开始计数，且包含该列。

nextPageToken string

用于下一页的不透明游标。没有更多结果时为空。
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'

响应结构：

{  "annotations": [    {      "id": "cra_01k2ja2000e0080000000000v1",      "checkRunId": "cr_01k2ja2000e0080000000000g7",      "annotationLevel": "warning",      "message": "Deprecated API usage; migrate to the v2 client.",      "title": "Deprecated API",      "createdAt": "2026-08-02T14:45:00Z",      "updatedAt": "2026-08-02T14:45:00Z",      "location": {        "path": "src/telemetry.ts",        "startLine": 42,        "endLine": 42      }    }  ]}

创建检查运行注解

POST/v1/origin/repos/{ownerSlug}/{repoName}/check-runs/{checkRunId}/annotations
Scoperepository:checks:writeAuthInstallation token

以单个原子批次向一次检查运行添加 1 至 25 条注释。

单次检查运行最多包含 100 条注释。若某个批次会使其超过此限制，则该批次会被拒绝并返回 ResourceExhausted (HTTP 429) ，且不会写入任何内容；批次大小若不在 1 到 25 的范围内，则会被拒绝并返回 InvalidArgument (HTTP 400) 。此操作仅支持追加且不具备幂等性，因此在发生不明确的传输故障后重试可能会追加重复项并消耗容量。允许完全相同的内容。

路径参数

ownerSlug string 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

checkRunId string 必填

服务器分配的 check run ID。

请求体

annotations array 必填

要追加的批次。必须包含 1 到 25 个条目。

annotations[].annotationLevel string 必填

注解的严重级别。可选值：notice、warning、failure。

annotations[].message string 必填

注解消息。不能为空。最大 65,535 字节 (UTF-8) 。

annotations[].title string

注释标题。最长 255 个 Unicode 字符。

annotations[].rawDetails string

原始详情文本。最大为 65,535 字节的 UTF-8 文本。

annotations[].location object

注解所指向的源代码位置。若为不与具体代码行关联的运行级注解，可省略。

annotations[].location.path string 必填

代码仓库相对的规范文件路径。最大 4,096 字节 (UTF-8) 。

annotations[].location.startLine integer 必填

范围的起始行。从 1 开始计数，且包含该行。

annotations[].location.endLine integer 必填

范围的最后一行。从 1 开始计数且包含该行，且位于或在 startLine 之后。

annotations[].location.columns 对象

行内的列范围。仅当 startLine 与 endLine 为同一行时才支持，且两个列参数必须同时传入。

annotations[].location.columns.startColumn 整数

范围的起始列。从 1 开始计数，且包含该列。

annotations[].location.columns.endColumn 整数

范围的最后一列。从 1 开始计数且包含该列，取值不小于 startColumn。

响应字段

annotations array

此请求创建的注释。

annotations[].id string

稳定的 Origin 注释 ID。ID 可按时间排序。

annotations[].checkRunId string

此注释所属的检查运行的 ID。

annotations[].annotationLevel string

注解的严重性。可选值：notice、warning、failure。

annotations[].message string

注释信息。

annotations[].title string

注释标题。注释没有标题时不显示。

annotations[].rawDetails string

原始详情文本。若注释不含该内容，则不存在此字段。

annotations[].createdAt string

注释的创建时间 (RFC 3339) 。

annotations[].updatedAt string

注释最后一次更新的时间 (RFC 3339) 。

annotations[].location object

来源位置。运行级注释不包含此项。

annotations[].location.path string

相对于仓库的规范文件路径。

annotations[].location.startLine 整数

范围的起始行。从 1 开始计数，且包含该行。

annotations[].location.endLine integer

范围的最后一行。从 1 开始计数，且包含该行。

annotations[].location.columns 对象

列范围。仅当注解覆盖单行时才会出现。

annotations[].location.columns.startColumn 整数

范围的起始列。从 1 开始计数，且包含该列。

annotations[].location.columns.endColumn 整数

范围的最后一列。从 1 开始计数，且包含端点。
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": "Deprecated API usage; migrate to the v2 client.",      "title": "Deprecated API",      "location": {        "path": "src/telemetry.ts",        "startLine": 42,        "endLine": 42      }    }  ]}'

响应结构：

{  "annotations": [    {      "id": "cra_01k2ja2000e0080000000000v1",      "checkRunId": "cr_01k2ja2000e0080000000000g7",      "annotationLevel": "warning",      "message": "Deprecated API usage; migrate to the v2 client.",      "title": "Deprecated API",      "createdAt": "2026-08-02T14:45:00Z",      "updatedAt": "2026-08-02T14:45:00Z",      "location": {        "path": "src/telemetry.ts",        "startLine": 42,        "endLine": 42      }    }  ]}

重新请求检查运行

POST/v1/origin/repos/{ownerSlug}/{repoName}/check-runs/{checkRunId}/rerequest
Scoperepository:contents:writeAuthInstallation tokenUser access token

请求报告该检查运行的应用再次运行该检查。Origin 将该请求记录在运行的 rerequestedAt 字段中，并通过 repository.check_run.rerequested 通知所属应用。该应用通过为相同的 head SHA 和 key 发布新的运行 (可以是新建运行或对现有运行的更新) 来响应，从而清除 rerequestedAt 并存储所发布的状态。在该请求处于未处理状态期间，该运行的 status 为 rerequested；其 conclusion 和各时间字段仍描述已被取代的那次尝试。此调用返回的运行会设置 rerequestedAt，且 status 为 rerequested。

该运行必须为 completed，必须包含 isRerequestable，必须是其 key 的当前尝试，并且必须位于开放拉取请求的当前 head 上。其他情况将返回 FailedPrecondition (HTTP 400) 。

每次运行同时只能有一个待处理的重新请求。当 rerequestedAt 已设置时再次请求会返回 AlreadyExists (HTTP 409 Conflict) ；在拥有该运行的 app 作出响应后，该运行将再次变为可重新请求。任何持有 repository:contents:write 的主体都可以重新请求任意可重新请求的运行，无论由哪个 app 上报。若 checkRunId 未知或属于其他代码仓库，则返回 404。

路径参数

ownerSlug 字符串 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体范围内唯一。

checkRunId string 必填

服务器分配的检查运行 ID (cr_...) 。

请求体

该请求不接受任何字段。请发送空 JSON 对象。

响应字段

id string

服务器分配的检查运行标识符。

repository 对象

运行所用的代码仓库引用。

repository.id string

容器引用中的存储库标识符。

repository.name string

容器引用中的仓库名称。

repository.owner 对象

仓库的所有者引用。

repository.owner.slug string

面向 URL 的所有者 slug，与所有者 ID 配合使用，用于标识代码仓库的所有者。

repository.owner.id string

源所有者标识符。

repository.owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

checkSuite 对象

对所属检查套件的引用。

checkSuite.id 字符串

所属检查套件的服务器分配标识符。

sha string

运行关联的提交 SHA。

key string

由应用选择的稳定逻辑运行标识；必需的检查可在应用、套件键和此键上匹配。

name string

仅用于显示的运行名称；不会用于必需检查匹配。

status string

生命周期状态：排队中、进行中、已完成或已重新请求。已重新请求的运行是指已完成但已请求重新运行且所属应用尚未回应的运行：将其视为待处理，并按排队中的方式呈现。

conclusion string

已完成或已重新请求的运行会提供此字段：success、failure、neutral、cancelled、skipped、timed_out、action_required 或 stale。对于已重新请求的运行，此值是已被取代的那次尝试的结果，因此仅当 status 为 completed 时才应读取。

detailsUrl string

指向提供方完整结果页面的单独链接。

externalUpdatedAt string

外部更新时间戳，用于对更新进行排序，以防较旧的重试替换较新的状态。

startedAt string

提供方报告的 RFC 3339 开始时间 (如有提供) 。

completedAt string

提供方报告的 RFC 3339 完成时间 (如有提供) 。

createdAt string

运行创建时间戳 (RFC 3339) 。

updatedAt string

最新已持久化运行更新的 RFC 3339 时间戳。

externalId string

单次尝试的提供者标识。重复使用该标识可更新该次尝试；重试时请使用新的值。

actor 对象

生成此运行的公共参与者。

actor.user 对象

操作主体的用户变体。用户执行该操作时设置。

actor.user.id string

用户的公开标识符。

actor.user.email string

用户的电子邮件地址。存在 user 变体时始终设置。

actor.user.displayName string

用户的显示名称：账户的名和姓以空格连接，产品呈现的即为该名称。若账户没有名称则省略。

actor.user.handle string

用户已认领的个人资料用户名，不含 @ 前缀。仅在该个人资料公开可见时提供；否则省略。

actor.app 对象

操作主体的应用 (app) 变体。在应用执行该操作时设置。

actor.app.id string

应用的公开标识符。

actor.app.displayName string

app 注册的显示名称。无法解析该 app 时省略；对于 Cursor 的第一方托管主体也会省略。

actor.serviceAccount 对象

操作主体的服务账户变体。在服务账户执行该操作时设置。

actor.serviceAccount.id string

服务账户的公开标识符。

output 对象

供人阅读的结果对象，包含标题、摘要，以及在提供时的更长文本。

output.title string

输出的简短标题。最大长度：255 个字符。

output.summary string

输出摘要。可包含 Markdown。最大 UTF-8 大小：65535 字节。

output.text string

详细输出。可能包含 Markdown。最大 UTF-8 大小：65535 字节。

deadlineAt string

以 RFC 3339 时间戳记录的检查运行截止时间。若运行没有截止时间 (包括运行完成后) ，则不返回此字段。

isRerequestable boolean

上报该运行的应用是否声明此运行可重新请求。

rerequestedAt string

未处理重新请求的 RFC 3339 时间戳。若没有待处理的重新请求则不返回；当拥有该运行的应用再次发布时会被清除。设置该字段期间，status 为 rerequested，该运行保持在提交的最新检查状态并显示为待处理，conclusion 和时间信息仍保留被取代的结果；因此必需的检查会阻止合并，直到该应用作出响应。

rerequestedBy 对象

请求重新运行的主体，携带与 actor 相同的主体变体。只要设置了 rerequestedAt 字段此项即存在，并会与其一同清除。
curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/check-runs/CHECK_RUN_ID/rerequest' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{}'

响应结构：

{  "id": "cr_01k2ja2000e0080000000000g7",  "repository": {    "id": "repo_01k2ja2000e0080000000000q4",    "name": "rocket",    "owner": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    }  },  "checkSuite": {    "id": "crg_01k2ja2000e0080000000000h8"  },  "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",  "key": "ci-8842-unit-tests",  "name": "unit-tests",  "status": "rerequested",  "conclusion": "failure",  "detailsUrl": "https://ci.acme.dev/runs/8842",  "externalUpdatedAt": "2026-08-02T14:44:30Z",  "startedAt": "2026-08-02T14:40:00Z",  "completedAt": "2026-08-02T14:44:30Z",  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T15:02:10Z",  "externalId": "run-8842",  "actor": {    "app": {      "id": "app_01k2ja2000e0080000000000a1",      "displayName": "Acme CI"    }  },  "output": {    "title": "Unit tests",    "summary": "3 of 128 tests failed."  },  "isRerequestable": true,  "rerequestedAt": "2026-08-02T15:02:10Z",  "rerequestedBy": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  }}

获取检查套件

GET/v1/origin/repos/{ownerSlug}/{repoName}/check-suites/{checkSuiteId}
Scoperepository:checks:readAuthInstallation tokenUser access token

按服务器分配的 id (crg_...) 返回 check suite 元数据。不内嵌 check runs；如需获取该 suite 的 runs，请使用 ListCheckRunsForSuite。

路径参数

ownerSlug 字符串 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体范围内唯一。

checkSuiteId string 必填

服务器分配的检查套件 ID (crg_...) 。

响应字段

id string

由服务器分配的检查套件标识符。

repository 对象

该测试套件的代码仓库引用。

repository.id string

容器引用中的存储库标识符。

repository.name string

容器引用中的仓库名称。

repository.owner 对象

仓库的所有者引用。

repository.owner.slug string

面向 URL 的所有者 slug，与所有者 ID 配合使用，用于标识代码仓库的所有者。

repository.owner.id string

Origin 所有者标识符。

repository.owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

sha string

该测试套件关联的提交 SHA。

key string

由应用选择的稳定必需检查标识。必需检查基于应用和此密钥匹配，而不是基于名称。

name string

仅供显示的检查套件名称；不用于必需检查的匹配。

detailsUrl string

可选链接，指向提供方的套件级结果。

createdAt string

RFC 3339 套件创建时间戳。

updatedAt string

最新测试套件更新的 RFC 3339 时间戳。

externalId string

此次套件运行的提供方标识。

actor 对象

生成该套件的公共参与者。

actor.user 对象

操作主体的用户变体。用户执行该操作时设置。

actor.user.id string

用户的公开标识符。

actor.user.email string

用户的电子邮件地址。在存在 user 变体时始终设置。

actor.user.displayName string

用户显示名称：账户的名和姓以空格连接，产品中呈现的名称。账户无名称时省略。

actor.user.handle 字符串

用户已认领的个人资料简称 (handle) ，不含 @ 前缀。仅在该个人资料公开可见时提供；否则省略。

actor.app 对象

操作主体的应用变体。在应用执行该操作时设置。

actor.app.id string

应用的公开标识符。

actor.app.displayName string

应用已注册的显示名称。当应用无法解析，或在 Cursor 的第一方托管主体上时省略。

actor.serviceAccount 对象

操作主体的服务账户变体。服务账户执行该操作时设置。

actor.serviceAccount.id 字符串

服务帐户的公共标识符。
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'

响应结构：

{  "id": "crg_01k2ja2000e0080000000000h8",  "repository": {    "id": "repo_01k2ja2000e0080000000000q4",    "name": "rocket",    "owner": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    }  },  "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",  "key": "ci-8842",  "name": "CI",  "detailsUrl": "https://ci.acme.dev/runs/8842",  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z",  "externalId": "build-8842",  "actor": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  }}

列出套件的检查运行

GET/v1/origin/repos/{ownerSlug}/{repoName}/check-suites/{checkSuiteId}/check-runs
Scoperepository:checks:readAuthInstallation tokenUser access token

列出某个套件当前的检查运行。当某个运行键在该套件中被报告多次时，仅返回该键的最新一次尝试；已被取代的尝试将被省略。被重新请求的运行仍会保留在列表中并显示为待处理状态，其 status 为 rerequested 且 rerequestedAt 已设置，而已被取代的 conclusion 与时间信息保持不变，直到拥有它的应用作出响应。可通过 获取检查运行 并使用已被取代尝试自身的 id 来读取它。支持分页。

路径参数

ownerSlug 字符串 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

checkSuiteId 字符串 必填

服务器分配的检查套件 ID (crg_...) 。

查询参数

pageSize 整数

要返回的最大检查运行次数。未设置或为 0 时默认为 30。超过 100 的值会被限制为 100。

pageToken string

来自先前响应的 next_page_token 的不透明游标。第一页时为空。对该套件范围内最后看到的 check-run id 进行编码，因此在提供该令牌时，后续请求中的 page_size 将被忽略。

响应字段

checkRuns 数组

属于指定测试套件的分页检查运行。

checkRuns[].id string

服务器分配的检查运行标识符。

checkRuns[].repository 对象

本次运行的仓库引用。

checkRuns[].repository.id string

容器引用中的仓库标识符。

checkRuns[].repository.name string

容器引用中的仓库名称。

checkRuns[].repository.owner 对象

代码仓库的所有者引用。

checkRuns[].repository.owner.slug string

用于 URL 的所有者 slug，与所有者 ID 配合使用以标识仓库所有者。

checkRuns[].repository.owner.id string

源所有者标识符。

checkRuns[].repository.owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

checkRuns[].checkSuite 对象

对所属检查套件的引用。

checkRuns[].checkSuite.id string

包含该检查套件的服务器分配标识符。

checkRuns[].sha string

该运行关联的提交 SHA。

checkRuns[].key string

由应用选择的稳定逻辑运行标识；所需检查可能会匹配应用、套件键和此键。

checkRuns[].name string

仅供显示的运行名称；不用于必需检查匹配。

checkRuns[].status string

生命周期状态：已排队 (queued)、进行中 (in_progress)、已完成 (completed) 或已重新请求 (rerequested)。已重新请求的运行是指已完成且已请求重新运行但所属应用尚未响应的运行：将其视为待处理，并像已排队那样呈现。

checkRuns[].conclusion string

已完成或被重新请求的运行会包含此字段：success、failure、neutral、cancelled、skipped、timed_out、action_required 或 stale。对于被重新请求的运行，它是已被取代尝试的结论，因此仅当 status 为 completed 时才应读取。

checkRuns[].detailsUrl string

指向提供者完整结果页面的独立链接。

checkRuns[].externalUpdatedAt string

用于对更新进行排序的外部更新时间戳，以防过时的重试替换较新的状态。

checkRuns[].startedAt string

提供方上报的 RFC 3339 格式开始时间 (若提供) 。

checkRuns[].completedAt string

提供方上报的 RFC 3339 格式完成时间 (若提供) 。

checkRuns[].createdAt string

运行创建时间戳，采用 RFC 3339 格式。

checkRuns[].updatedAt string

最新已持久化运行更新的 RFC 3339 时间戳。

checkRuns[].externalId string

单次尝试的提供者标识。重用它可用于更新该尝试；如需重试，请使用新的值。

checkRuns[].actor 对象

发起该运行的公共主体。

checkRuns[].actor.user 对象

actor 的用户变体。用户执行该操作时设置。

checkRuns[].actor.user.id string

用户的公开标识符。

checkRuns[].actor.user.email string

用户的电子邮件地址。存在用户变体时始终设置。

checkRuns[].actor.user.displayName string

用户的显示名称：账户的名和姓以空格连接，与产品中显示的名称相同。若账户没有名称则省略。

checkRuns[].actor.user.handle string

用户声明的个人资料账号名，不含 @ 前缀。仅在该资料公开可见时提供；否则省略。

checkRuns[].actor.app 对象

actor 的应用变体。在应用执行该操作时设置。

checkRuns[].actor.app.id string

应用的公开标识符。

checkRuns[].actor.app.displayName string

应用注册的显示名称。当应用无法解析，或主体为 Cursor 第一方托管主体时，将省略此项。

checkRuns[].actor.serviceAccount 对象

actor 的服务账号变体。服务账号执行该操作时设置。

checkRuns[].actor.serviceAccount.id string

服务账户的公开标识符。

checkRuns[].output 对象

供人类阅读的结果对象，包含标题、摘要，以及 (如提供) 更详尽的文本。

checkRuns[].output.title string

输出的简短标题。最大长度：255 个字符。

checkRuns[].output.summary string

输出的摘要。可包含 Markdown。UTF-8 最大长度：65535 字节。

checkRuns[].output.text string

详细输出。可能包含 Markdown。最大 UTF-8 大小：65535 字节。

checkRuns[].deadlineAt string

以 RFC 3339 时间戳记录的检查运行截止时间。运行没有截止时间时不包含此字段，运行完成后亦然。

checkRuns[].isRerequestable boolean

上报的应用是否声明该运行可重新请求。

checkRuns[].rerequestedAt string

待处理重新请求的 RFC 3339 时间戳。没有待处理的重新请求时不包含此字段；拥有该运行的应用再次提交时会被清除。在其被设置期间，status 为 rerequested，该运行仍计入该提交的最新检查状态，并显示为待处理，而 conclusion 和各时间字段仍携带已被取代的结果；因此在该应用作出响应前，必需检查会阻止合并。

checkRuns[].rerequestedBy 对象

请求重新运行的主体，携带与 actor 相同的 actor 变体。只要设置了 rerequestedAt 就会存在，并会与其一同被清除。

nextPageToken string

用于下一页的不透明游标；没有更多页面时为空。
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'

响应结构：

{  "checkRuns": [    {      "id": "cr_01k2ja2000e0080000000000g7",      "repository": {        "id": "repo_01k2ja2000e0080000000000q4",        "name": "rocket",        "owner": {          "slug": "acme",          "id": "ns_01k2ja2000e0080000000000p3",          "type": "team"        }      },      "checkSuite": {        "id": "crg_01k2ja2000e0080000000000h8"      },      "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",      "key": "ci-8842-unit-tests",      "name": "unit-tests",      "status": "completed",      "conclusion": "success",      "detailsUrl": "https://ci.acme.dev/runs/8842",      "externalUpdatedAt": "2026-08-02T14:44:30Z",      "startedAt": "2026-08-02T14:40:00Z",      "completedAt": "2026-08-02T14:44:30Z",      "createdAt": "2026-08-01T09:30:00Z",      "updatedAt": "2026-08-02T14:45:00Z",      "externalId": "run-8842",      "actor": {        "user": {          "id": "user_01k2ja2000e0080000000000c3",          "email": "jane@acme.dev"        }      },      "output": {        "title": "Unit tests",        "summary": "128 tests passed.",        "text": "All suites green."      }    }  ]}

列出提交的检查运行

GET/v1/origin/repos/{ownerSlug}/{repoName}/commits/{sha}/check-runs
Scoperepository:checks:readAuthInstallation tokenUser access token

列出某次提交在所有检查套件中的当前检查运行：仅包含属于每个套件最新尝试的运行，并且在每个套件内每个运行键仅保留最新尝试。已被取代的尝试将被省略。被重新请求的运行会保留在列表中并显示为待处理，status 为 rerequested 且设置了 rerequestedAt，其已被取代的 conclusion 和时间保持不变，直到拥有该运行的应用作出响应。可通过其自身 ID 使用获取检查运行读取已被取代的尝试。可选择按检查名称和状态进行筛选。支持分页。

筛选器适用于折叠后的集合，因此一次运行以其最近一次尝试的状态进行匹配，筛选器不会重新呈现已被取代的尝试。页面 token 会嵌入它们签发时所用的筛选条件，因此在不同筛选条件下重放的 token 会被拒绝；当筛选条件更改时请重新开始分页。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体范围内唯一。

sha string 必填

要列出检查运行的提交 SHA (40 或 64 位十六进制) 。

查询参数

pageSize 整数

要返回的最大检查运行次数。未设置或为 0 时默认为 30。超过 100 的值会被限制为 100。

pageToken string

来自先前响应的 next_page_token 的不透明游标。第一页时为空。它编码了限定在此提交及下述筛选条件范围内的最后看到的 check-run ID，因此在提供该令牌时，后续请求中的 page_size 将被忽略；若在不同筛选条件下重用同一令牌，将返回 InvalidArgument (HTTP 400) 。

checkName string

可选的精确 check-run 名称筛选，与 checkRuns[].name 匹配。省略以列出任意名称下的运行。

status string

可选的状态筛选。允许的值：queued、in_progress、completed、rerequested。其他任何值将返回 InvalidArgument (HTTP 400) 。省略则列出任意状态的运行。

响应字段

checkRuns 数组

关联到已解析提交 SHA 的分页检查运行。

checkRuns[].id string

服务器分配的检查运行标识符。

checkRuns[].repository 对象

运行的仓库引用。

checkRuns[].repository.id string

容器引用中的存储库标识符。

checkRuns[].repository.name string

容器引用中的仓库名称。

checkRuns[].repository.owner 对象

该代码仓库的所有者引用。

checkRuns[].repository.owner.slug string

面向 URL 的 owner slug，与 owner ID 配合使用，用于标识代码仓库的所有者。

checkRuns[].repository.owner.id string

源所有者标识符。

checkRuns[].repository.owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

checkRuns[].checkSuite 对象

对所属检查套件的引用。

checkRuns[].checkSuite.id string

所属检查套件的服务器分配标识符。

checkRuns[].sha string

运行关联的提交 SHA。

checkRuns[].key string

由应用选择的稳定逻辑运行标识；必需的检查可能会根据应用、suite key 和此 key 进行匹配。

checkRuns[].name string

仅供显示的运行名称；不用于必需检查匹配。

checkRuns[].status string

生命周期状态：排队 (queued)、进行中 (in_progress)、已完成 (completed) 或已重新请求 (rerequested)。已重新请求的运行是指已完成但被请求重新运行、且所属应用尚未响应的运行：将其视为待处理，并像排队状态一样呈现。

checkRuns[].conclusion string

在已完成或已重新请求的运行中提供：success、failure、neutral、cancelled、skipped、timed_out、action_required 或 stale。对于已重新请求的运行，它是已被取代的那次尝试的结果，因此仅当 status 为 completed 时才应读取。

checkRuns[].detailsUrl string

指向提供商完整结果页面的单独链接。

checkRuns[].externalUpdatedAt string

用于对更新进行排序的外部更新时间戳，以防过期的重试覆盖较新的状态。

checkRuns[].startedAt string

由提供方上报的 RFC 3339 格式开始时间 (如有提供) 。

checkRuns[].completedAt string

由提供方上报的 RFC 3339 格式完成时间 (如有提供) 。

checkRuns[].createdAt string

RFC 3339 运行创建时间戳。

checkRuns[].updatedAt string

最新已保存运行更新的 RFC 3339 时间戳。

checkRuns[].externalId 字符串

单次尝试的提供者标识。重用该标识以更新该尝试；重试时请使用新的值。

checkRuns[].actor 对象

生成该运行的公共主体。

checkRuns[].actor.user 对象

操作主体的用户变体。用户执行该操作时设置。

checkRuns[].actor.user.id string

用户的公开标识符。

checkRuns[].actor.user.email string

用户的电子邮件地址。存在用户变体时始终设置。

checkRuns[].actor.user.displayName string

用户显示名称：账户的名字和姓氏以空格连接，与产品中显示的名称相同。若账户没有名称则省略。

checkRuns[].actor.user.handle string

用户声明的个人资料用户名，不含 @ 前缀。仅在该资料公开可见时提供；否则省略。

checkRuns[].actor.app 对象

操作主体的应用变体。由应用执行该操作时设置。

checkRuns[].actor.app.id string

应用的公开标识符。

checkRuns[].actor.app.displayName string

应用已注册的显示名称。当应用无法解析或在 Cursor 托管的第一方主体上时将省略。

checkRuns[].actor.serviceAccount 对象

操作主体的服务账户变体。在服务账户执行该操作时设置。

checkRuns[].actor.serviceAccount.id string

服务账户的公开标识符。

checkRuns[].output 对象

供人阅读的结果对象，包含标题、摘要，以及 (如提供) 更长的文本。

checkRuns[].output.title string

输出的简短标题。最大长度：255 个字符。

checkRuns[].output.summary string

输出摘要。可包含 Markdown。UTF-8 最大长度：65535 字节。

checkRuns[].output.text string

详细输出。可能包含 Markdown。最大 UTF-8 大小：65535 字节。

checkRuns[].deadlineAt string

以 RFC 3339 时间戳记录的检查运行截止时间。当运行没有截止时间时 (包括运行完成后) ，此字段为空。

checkRuns[].isRerequestable boolean

上报应用是否将此次运行声明为可重新请求。

checkRuns[].rerequestedAt string

未处理的重新请求的 RFC 3339 时间戳。没有待处理的重新请求时为空；当拥有该运行的应用再次发布时会被清除。该字段设置期间，status 为 rerequested，该运行保持在提交的最新检查状态并显示为待处理，conclusion 和时间信息仍保留被取代的结果，因此在该应用响应之前，必需的检查会阻止合并。

checkRuns[].rerequestedBy 对象

请求重新运行的主体，携带与 actor 相同的 actor 变体。只要设置了 rerequestedAt 就会存在，并随其一同清除。

nextPageToken string

用于获取下一页的不透明游标；没有更多页面时为空。
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'

响应结构：

{  "checkRuns": [    {      "id": "cr_01k2ja2000e0080000000000g7",      "repository": {        "id": "repo_01k2ja2000e0080000000000q4",        "name": "rocket",        "owner": {          "slug": "acme",          "id": "ns_01k2ja2000e0080000000000p3",          "type": "team"        }      },      "checkSuite": {        "id": "crg_01k2ja2000e0080000000000h8"      },      "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",      "key": "ci-8842-unit-tests",      "name": "unit-tests",      "status": "completed",      "conclusion": "success",      "detailsUrl": "https://ci.acme.dev/runs/8842",      "externalUpdatedAt": "2026-08-02T14:44:30Z",      "startedAt": "2026-08-02T14:40:00Z",      "completedAt": "2026-08-02T14:44:30Z",      "createdAt": "2026-08-01T09:30:00Z",      "updatedAt": "2026-08-02T14:45:00Z",      "externalId": "run-8842",      "actor": {        "user": {          "id": "user_01k2ja2000e0080000000000c3",          "email": "jane@acme.dev"        }      },      "output": {        "title": "Unit tests",        "summary": "128 tests passed.",        "text": "All suites green."      }    }  ]}

列出提交的检查套件

GET/v1/origin/repos/{ownerSlug}/{repoName}/commits/{sha}/check-suites
Scoperepository:checks:readAuthInstallation tokenUser access token

列出针对某次提交上报的检查套件。仅返回每个上报主体和套件键对应的最新尝试；被替代的尝试将被省略。可通过其自身 ID 使用 获取检查套件 读取已被替代的尝试。仅返回套件元数据 (不包含嵌入的运行) 。支持分页。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

sha string 必填

要列出其套件的提交 SHA (40 或 64 个十六进制字符) 。

查询参数

pageSize 整数

要返回的最大套件数。未设置或为 0 时默认为 30。超过 100 的值将被限制为 100。

pageToken string

来自先前响应的 next_page_token 的不透明游标。对于第一页为空。该游标编码了限定于此提交的最后一次看到的 check-suite id，因此在提供令牌时，后续请求中的 page_size 会被忽略。

响应字段

checkSuites 数组

与已解析的提交 SHA 关联的分页检查套件。

checkSuites[].id string

服务器分配的检查套件标识符。

checkSuites[].repository 对象

该测试套件的代码仓库引用。

checkSuites[].repository.id string

容器引用中的仓库标识符。

checkSuites[].repository.name string

容器引用中的仓库名称。

checkSuites[].repository.owner 对象

存储库的所有者引用。

checkSuites[].repository.owner.slug string

与所有者 ID 一起使用以识别仓库所有者的面向 URL 的所有者 slug。

checkSuites[].repository.owner.id string

源所有者标识符。

checkSuites[].repository.owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

checkSuites[].sha string

该套件关联的 Commit SHA。

checkSuites[].key string

由应用选择的稳定必需检查标识。必需检查基于应用和此密钥匹配，而不是名称。

checkSuites[].name string

仅用于显示的测试套件名称；不用于必需检查匹配。

checkSuites[].detailsUrl string

可选链接，指向提供者的套件级结果。

checkSuites[].createdAt string

RFC 3339 套件创建时间戳。

checkSuites[].updatedAt string

最新套件更新的 RFC 3339 时间戳。

checkSuites[].externalId string

本次套件尝试的提供者身份。

checkSuites[].actor object

生成该套件的公共主体。

checkSuites[].actor.user object

操作者的用户变体。在用户执行该操作时设置。

checkSuites[].actor.user.id string

用户的公开标识符。

checkSuites[].actor.user.email string

用户的电子邮件地址。存在用户变体时始终设置。

checkSuites[].actor.user.displayName string

用户显示名称：账户的名字和姓氏以空格连接，与产品中呈现的名称相同。若账户没有名称则省略。

checkSuites[].actor.user.handle string

用户已认领的资料句柄，不含 @ 前缀。仅在该资料公开可见时存在；否则省略。

checkSuites[].actor.app 对象

操作者的应用程序变体。在应用执行该操作时设置。

checkSuites[].actor.app.id string

应用的公开标识符。

checkSuites[].actor.app.displayName string

应用注册的显示名称。若应用无法解析，或在 Cursor 的第一方托管 actor 上，将省略此字段。

checkSuites[].actor.serviceAccount 对象

操作者的服务帐户变体。在服务帐户执行该操作时设置。

checkSuites[].actor.serviceAccount.id string

服务账户的公共标识符。

nextPageToken string

用于下一页的不透明游标；没有更多页面时为空。
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'

响应结构：

{  "checkSuites": [    {      "id": "crg_01k2ja2000e0080000000000h8",      "repository": {        "id": "repo_01k2ja2000e0080000000000q4",        "name": "rocket",        "owner": {          "slug": "acme",          "id": "ns_01k2ja2000e0080000000000p3",          "type": "team"        }      },      "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",      "key": "ci-8842",      "name": "CI",      "detailsUrl": "https://ci.acme.dev/runs/8842",      "createdAt": "2026-08-01T09:30:00Z",      "updatedAt": "2026-08-02T14:45:00Z",      "externalId": "build-8842",      "actor": {        "user": {          "id": "user_01k2ja2000e0080000000000c3",          "email": "jane@acme.dev"        }      }    }  ]}

提交和内容

提交将 commit 中的 Git 对象元数据与仓库顶层关系分开。列表响应不包含 stats；获取提交包含整个提交的聚合 stats。修改的文件仅通过分页的列出提交文件集合返回。author 和 committer 是记录在提交中的 Git 身份，而非 Origin 用户对象。

比较仅提供摘要：绝不会嵌入提交列表或文件 diff。status 的值仅为 identical、ahead、behind 或 diverged；aheadBy 和 behindBy 表示提交数量。baseCommit、headCommit 和 mergeBaseCommit 使用精简的提交投影 (不含 stats 或文件) 。

列出提交

GET/v1/origin/repos/{ownerSlug}/{repoName}/commits
Scoperepository:contents:readAuthInstallation tokenUser access token

列出指定分支或起始引用上的提交。

列表结果省略 stats。对于聚合统计，请使用 获取提交；对于分页的文件差异，请使用 列出提交文件。

路径参数

ownerSlug string 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属主体内唯一。

查询参数

sha string

列出提交的起始 SHA、分支、标签或符号引用 (例如 HEAD) 。留空则使用仓库的默认分支。

pageSize integer

返回的最大提交数。未设置或为 0 时默认为 30。超过 100 的值将被限制为 100。

pageToken string

来自先前响应中 next_page_token 的不透明游标。第一页时为空。该游标编码了起始引用和页码，因此在提供 token 时，后续请求中的 sha/page_size 会被忽略。

响应字段

commits 数组

稀疏提交不包含统计信息；已更改的文件未嵌入。

commits[].sha string

完整提交 SHA。

commits[].commit 对象

与仓库顶层关系分开嵌套的 Git 对象元数据。

commits[].commit.author 对象

记录在提交中的 Git 作者身份，而非 Origin 用户对象。

commits[].commit.author.name string

在 Git 作者身份中记录的名称。

commits[].commit.author.email string

记录在 Git 作者身份中的电子邮件。

commits[].commit.author.date string

在 Git 作者身份中记录的 RFC 3339 日期。

commits[].commit.committer 对象

记录在提交中的 Git 提交者身份，而不是 Origin 用户对象。

commits[].commit.committer.name string

在 Git 身份中记录的名称。

commits[].commit.committer.email string

记录在 Git 身份中的电子邮件。

commits[].commit.committer.date string

保留 Git 签名原始时区偏移的 ISO-8601 时间戳 (例如 "2014-11-07T22:01:45+01:00") 。

commits[].commit.message string

提交信息。

commits[].commit.tree 对象

该提交引用的树。

commits[].commit.tree.sha string

提交所引用的树的 SHA。

commits[].parents 数组

父提交引用，每个包含一个 SHA。

commits[].parents[].sha string

父提交的 SHA。

nextPageToken string

下一页的不透明游标；当没有更多页面时为空。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/commits' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "commits": [    {      "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",      "commit": {        "author": {          "name": "Jane Doe",          "email": "jane@acme.dev",          "date": "2026-08-01T09:30:00Z"        },        "committer": {          "name": "Jane Doe",          "email": "jane@acme.dev",          "date": "2026-08-01T09:30:00Z"        },        "message": "Add launch telemetry",        "tree": {          "sha": "a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8"        }      },      "parents": [        {          "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"        }      ],      "stats": {        "additions": 128,        "deletions": 46,        "total": 174      }    }  ]}

获取提交

GET/v1/origin/repos/{ownerSlug}/{repoName}/commits/{sha}
Scoperepository:contents:readAuthInstallation tokenUser access token

按 SHA 或引用返回单个提交，并包含整个提交的汇总统计 stats。它不包括已更改的文件；请使用 列出提交文件。

author 和 committer 是提交中记录的 Git 身份，而不是 Origin 的用户对象。

路径参数

ownerSlug 字符串 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属所有者实体中唯一。

sha string 必填

要获取的提交的 SHA、分支、标签或符号引用 (例如 HEAD) 。

响应字段

sha string

完整的提交 SHA。

commit 对象

与顶层仓库关系分离嵌套的 Git 对象元数据。

commit.author 对象

提交中记录的 Git 作者身份，而不是 Origin 用户对象。

commit.author.name string

在 Git 作者身份中记录的名称。

commit.author.email string

在 Git 作者身份中记录的电子邮件。

commit.author.date string

Git 作者身份中记录的 RFC 3339 日期。

commit.committer 对象

提交中记录的是 Git 提交者身份，而不是 Origin 用户对象。

commit.committer.name string

在 Git 身份中记录的名称。

commit.committer.email string

记录在 Git 身份中的电子邮件。

commit.committer.date string

保留 Git 签名原始时区偏移的 ISO-8601 时间戳 (例如 "2014-11-07T22:01:45+01:00") 。

commit.message string

提交信息。

commit.tree 对象

该提交引用的树。

commit.tree.sha string

提交引用的 tree 的 SHA。

parents 数组

父提交引用，每一项包含一个 SHA。

parents[].sha string

父提交的 SHA。

stats object

整个提交的新增、删除与总计；由 get-commit 包含，在 list 投影中省略。

stats.additions integer

该提交新增行数汇总。

stats.deletions 整数

汇总该提交删除的行数。

stats.total 整数

该提交的新增与删除行数之和。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/commits/SHA' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",  "commit": {    "author": {      "name": "Jane Doe",      "email": "jane@acme.dev",      "date": "2026-08-01T09:30:00Z"    },    "committer": {      "name": "Jane Doe",      "email": "jane@acme.dev",      "date": "2026-08-01T09:30:00Z"    },    "message": "Add launch telemetry",    "tree": {      "sha": "a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8"    }  },  "parents": [    {      "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"    }  ],  "stats": {    "additions": 128,    "deletions": 46,    "total": 174  }}

列出提交中的文件

GET/v1/origin/repos/{ownerSlug}/{repoName}/commits/{sha}/files
Scoperepository:contents:readAuthInstallation tokenUser access token

列出某次提交中修改的文件。

sha 可以是提交 SHA、分支、标签或诸如 HEAD 的符号引用。结果默认返回 30 个文件，最多为 100 个。分页令牌会固定已解析的提交、页面大小和文件游标；在后续请求中，sha 和 pageSize 必须与该令牌匹配。每个文件包含 filename、status、additions、deletions、changes、patch，以及在重命名或复制时的 previousFilename。二进制文件的 patch 为空。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

sha string 必填

要列出文件的提交的 SHA、分支、标签或符号引用 (例如 HEAD) 。

查询参数

pageSize integer

返回的最大变更文件数。未设置或为 0 时默认为 30。超过 100 的值会被限制为 100。

pageToken string

来自先前响应的 next_page_token 的不透明游标。第一页为空。该令牌固定了解析的提交、页面大小和文件游标，因此后续请求中的 sha 和 page_size 必须与该令牌匹配。

响应字段

files 数组

分页返回修改的文件，包括文件名、状态、行数、补丁，以及重命名或复制文件的 previousFilename (原文件名) 。二进制补丁为空。

files[].filename string

修改的文件的路径。

files[].status string

变更状态：新增、删除、修改、重命名或复制。

files[].additions 整数

为该文件添加了行数。

files[].deletions integer

该文件删除的行数。

files[].changes integer

文件的修改行数总计。

files[].patch string

统一补丁；二进制文件则为空。

files[].previousFilename string

文件重命名或复制前的路径。

nextPageToken string

令牌会固定已解析的提交、页面大小和文件游标；后续的 sha 和 pageSize 值必须与之匹配。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/commits/SHA/files' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

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

比较提交

GET/v1/origin/repos/{ownerSlug}/{repoName}/compare/{basehead}
Scoperepository:contents:readAuthInstallation tokenUser access token

比较相对于其合并基的提交、引用或标签。basehead 为 "{base}...{head}"；包含 "/" 的引用必须使用其 SHA。

base 和 head 均可为 SHA、分支、标签或诸如 HEAD 的符号引用。响应为非分页摘要：status 为 identical、ahead、behind 或 diverged；三个提交对象为精简形式，省略 stats 和文件。不返回 totalCommits、嵌入的 commits 或 files 字段。无关联的历史将返回 404。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，对所属拥有者实体唯一。

basehead string 必填

"{base}...{head}"，其中任一修订可以是 SHA、分支、标签或符号引用 (例如 HEAD) 。

响应字段

status string

比较状态：完全相同、领先、落后或已分歧。

aheadBy 整数

head 超前的提交数。

behindBy 整数

head 落后的提交数。

baseCommit 对象

已解析的稀疏基准提交，不包含统计信息或文件。

baseCommit.sha string

完整的提交 SHA。

baseCommit.commit 对象

Git 对象元数据与顶层仓库关系分开嵌套。

baseCommit.commit.author object

提交中记录的 Git 作者身份，而非 Origin 用户对象。

baseCommit.commit.author.name string

在 Git 作者身份中记录的名称。

baseCommit.commit.author.email string

记录在 Git 作者身份中的电子邮件。

baseCommit.commit.author.date string

Git 作者身份中记录的 RFC 3339 日期。

baseCommit.commit.committer 对象

提交中记录的 Git 提交者身份，而不是 Origin 用户对象。

baseCommit.commit.committer.name string

在 Git 身份中记录的名称。

baseCommit.commit.committer.email string

在 Git 身份中记录的电子邮件。

baseCommit.commit.committer.date string

保留 git 签名原始时区偏移的 ISO-8601 时间戳 (例如 "2014-11-07T22:01:45+01:00") 。

baseCommit.commit.message string

提交信息。

baseCommit.commit.tree 对象

该提交引用的树。

baseCommit.commit.tree.sha string

该提交所引用的树对象的 SHA。

baseCommit.parents 数组

父提交引用，每个引用都包含一个 SHA。

baseCommit.parents[].sha string

父提交的 SHA。

headCommit 对象

稀疏解析的 head 提交，不包含统计信息或文件。

headCommit.sha string

完整的提交 SHA。

headCommit.commit 对象

Git 对象的元数据与顶层仓库关系分开嵌套。

headCommit.commit.author 对象

提交中记录的 Git 作者身份，而非 Origin 用户对象。

headCommit.commit.author.name string

在 Git 作者身份中记录的名称。

headCommit.commit.author.email string

记录在 Git 作者身份中的电子邮件。

headCommit.commit.author.date string

Git 作者身份中记录的 RFC 3339 日期。

headCommit.commit.committer 对象

提交中记录的 Git 提交者身份，而不是 Origin 用户对象。

headCommit.commit.committer.name string

在 Git 身份中记录的名称。

headCommit.commit.committer.email string

在 Git 身份中记录的电子邮件。

headCommit.commit.committer.date string

保留 git 签名原始时区偏移的 ISO-8601 时间戳 (例如 "2014-11-07T22:01:45+01:00") 。

headCommit.commit.message string

提交信息。

headCommit.commit.tree 对象

该提交引用的树。

headCommit.commit.tree.sha string

该提交所引用的树对象的 SHA。

headCommit.parents 数组

父提交引用，每个引用都包含一个 SHA。

headCommit.parents[].sha string

父提交的 SHA。

mergeBaseCommit 对象

稀疏的 merge-base 提交，不包含统计信息或文件。

mergeBaseCommit.sha string

完整的提交 SHA。

mergeBaseCommit.commit 对象

Git 对象元数据与顶层仓库关系分开嵌套。

mergeBaseCommit.commit.author 对象

提交中记录的 Git 作者身份，而非 Origin 用户对象。

mergeBaseCommit.commit.author.name string

在 Git 作者身份中记录的名称。

mergeBaseCommit.commit.author.email string

记录在 Git 作者身份中的电子邮件。

mergeBaseCommit.commit.author.date string

Git 作者身份中记录的 RFC 3339 日期。

mergeBaseCommit.commit.committer 对象

提交中记录的 Git 提交者身份，而不是 Origin 用户对象。

mergeBaseCommit.commit.committer.name string

在 Git 身份中记录的名称。

mergeBaseCommit.commit.committer.email string

在 Git 身份中记录的电子邮件。

mergeBaseCommit.commit.committer.date string

保留 git 签名原始时区偏移的 ISO-8601 时间戳 (例如 "2014-11-07T22:01:45+01:00") 。

mergeBaseCommit.commit.message string

提交信息。

mergeBaseCommit.commit.tree 对象

该提交引用的树。

mergeBaseCommit.commit.tree.sha string

该提交所引用的树对象的 SHA。

mergeBaseCommit.parents 数组

父提交引用，每个都包含一个 SHA。

mergeBaseCommit.parents[].sha string

父提交的 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'

响应结构：

{  "status": "ahead",  "aheadBy": 2,  "behindBy": 0,  "baseCommit": {    "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",    "commit": {      "author": {        "name": "Jane Doe",        "email": "jane@acme.dev",        "date": "2026-08-01T09:30:00Z"      },      "committer": {        "name": "Jane Doe",        "email": "jane@acme.dev",        "date": "2026-08-01T09:30:00Z"      },      "message": "Add launch telemetry",      "tree": {        "sha": "a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8"      }    },    "parents": [      {        "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"      }    ],    "stats": {      "additions": 128,      "deletions": 46,      "total": 174    }  },  "headCommit": {    "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "commit": {      "author": {        "name": "Jane Doe",        "email": "jane@acme.dev",        "date": "2026-08-01T09:30:00Z"      },      "committer": {        "name": "Jane Doe",        "email": "jane@acme.dev",        "date": "2026-08-01T09:30:00Z"      },      "message": "Add launch telemetry",      "tree": {        "sha": "a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8"      }    },    "parents": [      {        "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"      }    ],    "stats": {      "additions": 128,      "deletions": 46,      "total": 174    }  },  "mergeBaseCommit": {    "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",    "commit": {      "author": {        "name": "Jane Doe",        "email": "jane@acme.dev",        "date": "2026-08-01T09:30:00Z"      },      "committer": {        "name": "Jane Doe",        "email": "jane@acme.dev",        "date": "2026-08-01T09:30:00Z"      },      "message": "Add launch telemetry",      "tree": {        "sha": "a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8"      }    },    "parents": [      {        "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"      }    ],    "stats": {      "additions": 128,      "deletions": 46,      "total": 174    }  }}

列出比较中的文件

GET/v1/origin/repos/{ownerSlug}/{repoName}/compare/{basehead}/files
Scoperepository:contents:readAuthInstallation tokenUser access token

列出一次比较中修改的文件：head 与 base 和 head 的合并基点之间的 diff。

basehead 为 "{base}...{head}"；包含 "/" 的引用必须使用其 SHA。文件列表始终与 比较提交 中的摘要一致，因此 identical 或 behind 比较会返回空列表，而无关联的历史记录会返回 404。结果默认返回 30 个文件，最多为 100 个。每个文件包含与 列出提交文件 相同的字段。

路径参数

ownerSlug string 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

basehead string 必填

"{base}...{head}"，其中任一修订版本都可以是 SHA、分支、标签或诸如 HEAD 的符号引用。

查询参数

pageSize integer

返回的最大修改文件数。未设置或为 0 时默认值为 30。超过 100 的值会被限制为 100。

pageToken string

来自先前响应的 next_page_token 的不透明游标。第一页为空。该令牌绑定到已解析的比较、页面大小和文件游标，因此后续请求中的 basehead 和 page_size 必须与该令牌匹配。Origin 会在每一页重新解析比较；如果自令牌发放以来其提交已发生变动，请求将返回 InvalidArgument (HTTP 400) ，且必须从第一页重新开始列出。

响应字段

files 数组

分页返回修改的文件，包括文件名、状态、行数、补丁，以及重命名或复制文件的 previousFilename (原文件名) 。二进制补丁为空。

files[].filename string

修改的文件的路径。

files[].status string

变更状态：新增、删除、修改、重命名或复制。

files[].additions 整数

为该文件添加的行数。

files[].deletions integer

该文件被删除的行数。

files[].changes integer

文件的修改行数总计。

files[].patch string

统一补丁；二进制文件则为空。

files[].previousFilename string

文件重命名或复制前的路径。

nextPageToken string

下一页的不透明游标；没有更多文件时为空。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/compare/BASE...HEAD/files' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

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

获取内容

GET/v1/origin/repos/{ownerSlug}/{repoName}/contents
Scoperepository:contents:readAuthInstallation tokenUser access token

返回指定引用中文件或目录的内容。通过 path 查询参数传入文件路径 (支持嵌套路径) ；省略或留空则返回代码仓库根目录。解码后大于 1 MiB 的文件会因 FailedPrecondition (HTTP 400) 被拒绝。

文件包含 base64 内容。目录在 entries 中包含直接子项。目录条目是仅包含 type、name、path、sha 和 size 的子项；获取子项路径以读取其内容。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

查询参数

path string

相对于代码仓库根目录的文件或目录路径。留空则请求根目录。

ref string

要读取的提交、分支、标签或符号引用 (例如 HEAD) 。留空表示使用代码仓库的默认分支。

响应字段

type string

内容类型：文件或目录。

encoding string

文件编码；文件响应使用 base64。

size string

按 API 的 64 位整数约定编码为 JSON string 的解码后内容字节大小。大于 1 MiB 的文件负载会被拒绝。

name string

文件或目录的基本名称。

path string

相对于代码仓库根目录的路径。

sha string

文件的 Blob SHA 或目录的 tree SHA。

content string

Base64 编码的文件响应体；获取文件时存在。

entries array

目录的直接稀疏子项。条目包含 type、name、path、sha 和 size；获取子项路径以读取其内容。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/contents' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "type": "file",  "encoding": "base64",  "size": "312",  "name": "telemetry.ts",  "path": "src/telemetry.ts",  "sha": "c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0",  "content": "Y29uc29sZS5sb2coImxhdW5jaCIpOwo="}

批量获取内容

POST/v1/origin/repos/{ownerSlug}/{repoName}/contents:batchGet
Scoperepository:contents:readAuthInstallation tokenUser access token

一次请求返回某引用下若干明确路径的内容。每个请求的路径都会返回一个结果以标明是否找到；已找到的路径具有与 GetContents 相同的 Content 结构 (文件为 base64，目录为直接的 entries，符号链接作为文件) 。路径必须精确匹配，不支持通配符或模式，最多可请求 20 个路径；重复项会被移除。响应结果按首次出现的请求顺序保留。如果单个文件超过 Get Contents 的 1 MiB 限制，整个批次将以 FailedPrecondition (HTTP 400) 失败。由于路径列表在请求体中传输，因此使用 POST。

路径参数

ownerSlug string 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属主体内唯一。

请求体

paths 数组 必填

要获取的精确路径，相对于仓库根目录 (不支持 glob 或通配模式) 。最多 20 个条目；重复项会被移除。空字符串表示请求仓库根目录。

ref string

要读取的提交、分支、标签或符号引用 (例如 HEAD) 。留空表示仓库的默认分支。

响应字段

results array

每个返回的精确路径只保留一个结果，按首次出现请求的顺序保留。

results[].path string

与此结果对应的请求路径。

results[].found 布尔值

请求的路径是否存在于已解析的提交中。

results[].content 对象

当 found 为 true 时返回内容值；当 found 为 false 时省略。

results[].content.type string

内容类型：文件或目录。

results[].content.encoding string

文件编码；文件响应使用 base64。

results[].content.size string

解码后内容的大小 (以字节为单位) ，根据 API 的 64 位整数约定编码为 JSON 字符串。超过 1 MiB 的文件负载将被拒绝。

results[].content.name string

文件或目录的基本名称。

results[].content.path string

相对于仓库根目录的路径。

results[].content.sha string

文件的 Blob SHA，或目录的 tree SHA。

results[].content.content string

文件内容为 Base64 编码；仅在已获取的文件中提供。

results[].content.entries array

目录的直接稀疏子项。条目包含类型、名称、路径、sha 和大小；获取子路径以读取其内容。

resolvedCommitSha string

所请求的引用解析到的提交 SHA。
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": [    "src/telemetry.ts"  ],  "ref": "main"}'

响应结构：

{  "results": [    {      "path": "src/telemetry.ts",      "found": true,      "content": {        "type": "file",        "encoding": "base64",        "size": "312",        "name": "telemetry.ts",        "path": "src/telemetry.ts",        "sha": "c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0",        "content": "Y29uc29sZS5sb2coImxhdW5jaCIpOwo="      }    }  ],  "resolvedCommitSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4"}

使用 grep 搜索内容

POST/v1/origin/repos/{ownerSlug}/{repoName}:grep
Scoperepository:contents:readAuthInstallation tokenUser access token

在指定引用处搜索代码仓库中文件的文本内容，返回匹配的行以及所请求的相邻上下文行。搜索以行为单位：模式不会跨换行符匹配，返回的每条结果都是一行。每次请求都会扫描整个代码仓库，因此没有分页，也没有游标；仅当 limitHit 为 false 时，响应才是完整的。若代码仓库为空且没有任何引用，则不返回任何匹配，且 limitHit 为 false。由于搜索参数通过请求体传递，因此使用 POST。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体中唯一。

请求体

ref string

要搜索的提交、分支、标签或符号引用 (例如 HEAD) 。留空则表示代码仓库的默认分支。

query string 必填

要搜索的模式。默认情况下为正则表达式，支持字符类、量词、选择分支、分组和锚点；如需精确匹配文本，请设置 literal。空白字符同样有效，会按原样参与搜索。空模式将返回 InvalidArgument (HTTP 400) 。UTF-8 最大长度：4096 字节。

literal boolean

将 query 作为精确文本搜索，而非正则表达式。

caseInsensitive boolean

匹配时不区分大小写。

wholeWord boolean

仅匹配完整单词。

contextBefore integer

返回每个匹配行紧前面的多少行作为上下文。大于 10 的值会被减少为 10。

contextAfter integer

指定在每个匹配行后返回多少行作为上下文。超过 10 的值将设为 10。

filterPath string

将搜索范围限制为相对于代码仓库根目录的此文件或目录。留空则搜索整个代码仓库。最大 UTF-8 大小：4096 字节。

includes 数组

用于指定待搜索路径的 glob 模式。匹配不区分大小写；不含 / 的模式可在任意深度匹配，* 仅在单个路径段内匹配，** 可跨路径段匹配。只要存在任一 include，未匹配其中任何一项的路径都不会被搜索。最多 20 个条目。每个模式的最大 UTF-8 大小：4096 字节。

excludes array

用于指定要排除的路径的 glob 模式，语法与 includes 相同。排除优先于包含，排除某个目录会同时排除其下的所有内容。最多 20 个条目。每个模式的 UTF-8 大小上限为 4096 字节。

maxResults 整数

返回的最大匹配项数。设为 0 表示使用默认值 1000，大于 1000 的值将按 1000 处理。上下文行不计入该上限。

响应字段

matches 数组

匹配的行及其上下文行。文件和行的出现顺序未指定；即使请求相同，顺序也可能不同。

matches[].path string

文件路径，相对于代码仓库根目录。

matches[].lineNumber 整数

该行在文件中的行号 (从 1 开始计数) 。

matches[].line string

该行的文本，不含末尾的行终止符。

matches[].kind string

此行是否包含匹配项，或是否作为上下文返回。允许的值：match、context。

matches[].submatches 数组

匹配项在 line 中的位置。上下文行上始终为空。当 limitHit 为 true 时，最后一个匹配行可能只包含部分匹配项。完全超出 line 范围的区间会被省略，超出 line 部分的区间会被截断为剩余的字节。

matches[].submatches[].start integer

匹配项首字节在该行内的字节偏移量。

matches[].submatches[].end integer

该行中匹配内容最后一个字节之后一个位置的字节偏移量。

limitHit boolean

搜索是否已达到 maxResults。缩小 query、filterPath 或 glob 列表的范围，以在更小的文件集合中搜索。
curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME:grep' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "ref": "main",  "query": "emitLaunchTelemetry\\(",  "contextBefore": 1,  "contextAfter": 1,  "includes": [    "*.ts"  ],  "excludes": [    "**/node_modules/**"  ],  "maxResults": 50}'
{  "matches": [    {      "path": "src/telemetry.ts",      "lineNumber": 11,      "line": "export function emitLaunchTelemetry(stage: string): void {",      "kind": "match",      "submatches": [        {          "start": 16,          "end": 37        }      ]    },    {      "path": "src/telemetry.ts",      "lineNumber": 12,      "line": "  console.log(\"launch\", stage);",      "kind": "context",      "submatches": []    }  ],  "limitHit": false}

Git 数据

底层 git 对象。读取需要 repository:contents:read，空仓库将返回 409。Create Commit From Files 和 Create Git Ref 会写入 git 对象，需要 repository:contents:write。

获取 Blob

GET/v1/origin/repos/{ownerSlug}/{repoName}/git/blobs/{sha}
Scoperepository:contents:readAuthInstallation tokenUser access token

根据 SHA 返回 Git blob 对象。默认响应为 JSON，content 包含 MIME 封装的 base64 内容。在 REST 接口中传递 Accept: application/vnd.origin.raw+json (或 application/vnd.origin.raw) ，即可改为获取原始 blob 字节。解码后大于 4 MiB 的 blob 将被拒绝；较大文件请通过 Git HTTPS 克隆仓库来获取。空仓库将返回 409 Conflict。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

sha string 必填

blob 对象的完整或缩写十六进制 SHA。

响应字段

sha string

Git blob 对象的 SHA。

size integer

解码后的 blob 大小，以 JSON 数值表示；JSON 端点会拒绝大于 4 MiB 的 blob。

encoding string

JSON blob 响应使用 base64 编码。

content string

经 base64 编码的 blob 字节；调用方可通过 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'

响应结构：

{  "sha": "c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0",  "size": 312,  "encoding": "base64",  "content": "Y29uc29sZS5sb2coImxhdW5jaCIpOwo="}

获取 Git 提交

GET/v1/origin/repos/{ownerSlug}/{repoName}/git/commits/{sha}
Scoperepository:contents:readAuthInstallation tokenUser access token

根据 SHA(或可解析的修订版本)返回 Git 提交对象。这是底层 Git 数据库的提交形态(扁平的 author/message/tree),而不是位于 /commits/{sha} 下的更高级别 GetCommit 资源。sha 可接受提交 SHA、分支、标签或符号引用(例如 HEAD)。空仓库将返回 409 Conflict。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属所有者实体中唯一。

sha string 必填

提交对象的完整或缩短的十六进制 SHA，或分支、标签，或如 HEAD 的符号引用。

响应字段

sha string

完整的提交 SHA (十六进制) 。

author 对象

来自 git 对象的作者签名。

author.name string

Git 身份中记录的名称。

author.email string

在 Git 身份中记录的电子邮件。

author.date string

ISO-8601 时间戳，保留 git 签名的原始时区偏移 (例如 "2014-11-07T22:01:45+01:00") 。

committer 对象

来自 git 对象的提交者签名。

committer.name string

Git 身份中记录的名称。

committer.email string

记录在 Git 身份中的电子邮件。

committer.date string

ISO-8601 时间戳，保留 git 签名的原始时区偏移 (例如 "2014-11-07T22:01:45+01:00") 。

message string

完整的提交消息。

tree 对象

此提交所指向的树。

tree.sha string

该提交所引用树的 SHA。

parents 数组

父提交的 SHA (根提交时为空) 。

parents[].sha string

父提交的 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'

响应结构：

{  "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",  "author": {    "name": "Jane Doe",    "email": "jane@acme.dev",    "date": "2026-08-01T09:30:00Z"  },  "committer": {    "name": "Jane Doe",    "email": "jane@acme.dev",    "date": "2026-08-01T09:30:00Z"  },  "message": "Add launch telemetry",  "tree": {    "sha": "a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8"  },  "parents": [    {      "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"    }  ]}

从文件创建 commit

POST/v1/origin/repos/{ownerSlug}/{repoName}/git/commits:createFromFiles
Scoperepository:contents:writeAuthInstallation tokenUser access token

根据内联文件更改在分支上创建提交，并将该分支推进到该提交。

更改会应用到 expectedHeadSha 所指向的 tree 上，该 tree 将成为新 commit 的 parent。以下情况均返回 FailedPrecondition (HTTP 400) ：branch 已移动或不存在；一组更改未对 tree 产生任何变化；删除 tree 中并不存在的 path；写入操作被 push 规则集拦截；代码仓库的内容是从其他 host mirror 而来。

单个请求最多可包含 1,000 项文件更改，每个文件最大 8 MiB，内容总计最大 32 MiB。超出限制、路径重复或字段格式有误都会返回 InvalidArgument (HTTP 400) ，并在 google.rpc.BadRequest 的字段校验错误中指明出问题的 files[i] 条目。

该分支必须已存在。请先通过 Create Git Ref 创建分支，然后再向其提交。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体范围内唯一。

请求体

targetBranch string 必填

接收该 commit 的分支，可写作 <branch>、heads/<branch> 或 refs/heads/<branch>。该分支必须已存在。HEAD 在任何写法下都会被拒绝。

expectedHeadSha string 必填

目标分支当前必须指向的完整十六进制 SHA。它将成为新提交的父提交。全零 SHA 会被拒绝。

message string 必填

提交信息。

author object 必填

提交作者。时间戳由服务器分配。

author.name string 必填

Git identity 中记录的 Name。

author.email string 必填

Git 身份中记录的电子邮件地址。

committer object

提交的提交者。省略时默认为 author。

committer.name string

记录在 Git 身份信息中的名称。存在 committer 时必填。

committer.email string

Git 身份中记录的电子邮件地址。存在 committer 时必填。

files 数组 必填

应用到分支 tip 所指向的 tree 上的文件更改。至少需要一项更改，且同一请求内的路径必须唯一。

files[].path string 必填

相对于代码仓库的路径，使用 / 作为分隔符，例如 docs/changelog.md。

files[].content string

新的文件内容，按 files[].encoding 编码。将创建该文件或替换其内容。files[].content 与 files[].delete 只能设置其中一个。

files[].delete boolean

删除该文件。设置时必须为 true。files[].content 和 files[].delete 二者必须且只能设置其一。

files[].encoding string

files[].content 的编码方式。允许的值：utf-8 (默认值) 、base64。删除操作会忽略此字段。

files[].mode string

files[].content 的文件模式。允许的值：file (默认值) 、executable、symlink (此时内容即为链接目标) 。删除操作会忽略此字段。

响应字段

sha string

新 commit 的 SHA，现为该 Branch 的 tip。

treeSha string

新 commit 的 root tree 的 SHA。

previousHeadSha string

写入操作之前的分支顶端；即新提交的父提交。
curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/git/commits:createFromFiles' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "targetBranch": "feature/login",  "expectedHeadSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",  "message": "Add login telemetry",  "author": {    "name": "Jane Doe",    "email": "jane@acme.dev"  },  "files": [    {      "path": "src/login/telemetry.ts",      "content": "export const LOGIN_EVENT = 1;"    },    {      "path": "assets/login.png",      "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",      "encoding": "base64"    },    {      "path": "src/login/legacy.ts",      "delete": true    }  ]}'

响应结构：

{  "sha": "5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d",  "treeSha": "a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8",  "previousHeadSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4"}

获取 Git 引用

GET/v1/origin/repos/{ownerSlug}/{repoName}/git/ref/{ref}
Scoperepository:contents:readAuthInstallation tokenUser access token

按名称获取单个 Git 引用。ref 通常为 heads/<branch> 或 tags/<tag> (可带或不带前导 refs/) ，也可以是符号引用 HEAD。仅支持精确匹配；如需按前缀匹配，请使用 ListMatchingGitRefs。空仓库返回 409 Conflict。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

ref string 必填

Git 引用名称。通常为 heads/<branch> 或 tags/<tag>；可接受前导 refs/，并会将其规范化。也接受符号引用 HEAD (返回为 ref: "HEAD"，并附带最新提交) 。按完整引用名称精确匹配。

响应字段

ref string

完整引用名称，例如 "refs/heads/main"。

object object

此引用直接指向的对象 (未剥离) 。对于带注释的标签，object.type 为 "tag"，object.sha 为标签对象的 SHA。

object.sha string

目标对象的十六进制 SHA。

object.type string

"commit"、"tree"、"blob" 或 "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'

响应结构：

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

创建 Git Ref

POST/v1/origin/repos/{ownerSlug}/{repoName}/git/refs
Scoperepository:contents:writeAuthInstallation tokenUser access token

创建指向现有 commit 的分支引用。

只能创建分支引用。tag 或任何其他引用 namespace，以及并非仓库中某个 commit 完整 hex SHA 的 sha，均返回 InvalidArgument (HTTP 400) 。若要创建的分支已指向该 sha，则操作成功并返回现有引用；若该分支已存在但指向其他 commit，则返回 AlreadyExists (HTTP 409 Conflict) 。若创建操作被 push 规则集阻止，或该代码仓库的内容镜像自其他 host，则返回 FailedPrecondition (HTTP 400) 。

Path Parameters

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体范围内唯一。

Request Body

ref string 必填

要创建的分支引用，格式为 refs/heads/<branch> 或 heads/<branch>。

sha string 必填

新分支所指向的现有 commit 的完整 hex SHA。

Response Fields

ref string

完整 ref 名称，例如 "refs/heads/main"。

object object

该 ref 直接指向的 object (unpeeled) 。对于分支，object.type 为 "commit"。

object.sha string

目标 object 的 hex SHA。

object.type string

为 "commit"、"tree"、"blob" 或 "tag" 之一。
curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/git/refs' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "ref": "refs/heads/feature/login",  "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4"}'

响应结构：

{  "ref": "refs/heads/feature/login",  "object": {    "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "type": "commit"  }}

列出匹配的 Git 引用

GET/v1/origin/repos/{ownerSlug}/{repoName}/git/matching-refs
Scoperepository:contents:readAuthInstallation tokenUser access token

列出名称以指定前缀开头的 Git 引用。REST 响应会解包为 JSON 数组 (通过 response_body) 。会保留 ref 的尾部斜杠 (heads/ → refs/heads/) 。符号引用 HEAD 会被精确匹配 (它不在 refs/ 下) 。空仓库返回 409 Conflict。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

查询参数

ref string

要匹配的前缀。通常为 heads/<prefix> 或 tags/<prefix>；可接受前导 refs/，并会将其规范化。留空时列出所有引用 (REST 绑定中不包含尾部路径段) 。

响应字段

响应为数组。每个项包含：

ref string

完整引用名称，例如 "refs/heads/main"。

object object

该引用直接指向的对象 (未剥离) 。对于带注释的标签，object.type 为 "tag"，object.sha 为标签对象的 SHA。

object.sha string

目标对象的十六进制 SHA。

object.type string

"commit"、"tree"、"blob" 或 "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'

响应结构：

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

按路径列出匹配的 Git 引用

GET/v1/origin/repos/{ownerSlug}/{repoName}/git/matching-refs/{ref}
Scoperepository:contents:readAuthInstallation tokenUser access token

列出名称以指定前缀开头的 Git 引用。REST 响应会解包为 JSON 数组 (通过 response_body) 。会保留 ref 尾部斜杠 (heads/ → refs/heads/) 。符号引用 HEAD 必须完全匹配 (不位于 refs/ 下) 。空仓库返回 409 Conflict。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

ref string 必填

要匹配的前缀。通常为 heads/<prefix> 或 tags/<prefix>；支持前导 refs/，并会将其规范化。为空时列出所有引用 (REST 绑定中不带尾部路径段) 。

响应字段

响应为一个数组。每个项包含：

ref string

完整的引用名称，例如 "refs/heads/main"。

object object

此引用直接指向的对象 (未剥离) 。对于带注释的标签，object.type 为 "tag"，object.sha 为标签对象 SHA。

object.sha string

目标对象的十六进制 SHA。

object.type string

"commit"、"tree"、"blob" 或 "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'

响应结构：

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

获取标签

GET/v1/origin/repos/{ownerSlug}/{repoName}/git/tags/{sha}
Scoperepository:contents:readAuthInstallation tokenUser access token

按 SHA 返回带注释的 Git 标签对象。轻量标签不属于标签对象，返回 NotFound。空仓库返回 409 Conflict。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

sha string 必填

带注释标签对象的完整或缩写十六进制 SHA。

响应字段

sha string

标签对象 SHA (十六进制) 。

tag string

标签名称，例如 "v1.0"。

message string

标签消息。

tagger object

标签对象中的打标签者签名。

tagger.name string

Git 身份中记录的名称。

tagger.email string

Git 身份中记录的电子邮件。

tagger.date string

保留 Git 签名原始时区偏移量的 ISO-8601 时间戳 (例如 "2014-11-07T22:01:45+01:00") 。

object object

此标签指向的对象。

object.sha string

目标对象的十六进制 SHA。

object.type string

"commit"、"tree"、"blob" 或 "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'

响应结构：

{  "sha": "e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2",  "tag": "v1.2.0",  "message": "Release v1.2.0",  "tagger": {    "name": "Jane Doe",    "email": "jane@acme.dev",    "date": "2026-08-01T09:30:00Z"  },  "object": {    "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "type": "commit"  }}

获取树

GET/v1/origin/repos/{ownerSlug}/{repoName}/git/trees/{sha}
Scoperepository:contents:readAuthInstallation tokenUser access token

根据 SHA 或可解析的修订版本返回 Git 树对象。sha 可接受树 SHA、提交 SHA、分支、标签或诸如 HEAD 的符号引用。将 recursive=true (或 1) 设置为遍历整个树；省略该参数或传入任何其他值则仅列出直接子项。递归列表在达到 100,000 个条目或 7 MiB 时会被截断，并设置 truncated=true。空仓库返回 409 Conflict。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

sha string 必填

树 SHA、提交 SHA、分支、标签或诸如 HEAD 的符号引用。

查询参数

recursive boolean

为 true 时，返回树的完整递归遍历。查询值 true 和 1 启用递归；省略该参数或传入任何其他值 (包括 false 和 0) 时，仅列出直接子项。

响应字段

sha string

树对象 SHA (十六进制) 。

tree array

此树下的条目 (直接子项，或完整递归遍历) 。

tree[].path string

相对于请求树根目录的路径。

tree[].mode string

以八进制字符串表示的 Git 模式："100644"、"100755"、"040000"、"120000"、"160000"。

tree[].type string

"blob"、"tree" 或 "commit" (gitlink/子模块) 之一。

tree[].sha string

对象 SHA (十六进制) 。

tree[].size integer

Blob 大小，单位为字节。对 trees 和 gitlink 不设置此字段。int32 可确保 REST JSON 输出为数字；单个 blob 超过 2 GiB 时无法表示。

truncated boolean

递归树列表被截断时，此值可能为 true。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/git/trees/SHA' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "sha": "a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8",  "tree": [    {      "path": "src/telemetry.ts",      "mode": "100644",      "type": "blob",      "sha": "c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0",      "size": 312    }  ],  "truncated": false}

Grants

一条 grant 将一个 principal 绑定到一个代码仓库或一个 owner，并授予一项权限。这些端点用于读取、设置和移除直接作用于某个 resource 上的 grant，从而让访问权限的更改可以像代码一样脚本化并接受评审。写入操作复用代码库权限 UI 背后的检查逻辑，并记录相同的 repository.access_changed 和 namespace.access_changed 审计事件。关于 principal 的类型、两套权限层级，以及 owner 级 grant 与代码仓库级 grant 如何相互作用，请阅读 Origin Grants API。

列出代码仓库授权

GET/v1/origin/repos/{ownerSlug}/{repoName}/grants
Scoperepository:settings:readAuthInstallation tokenUser access token

列出在某个代码仓库上直接获得权限的用户、群组及所属团队群组。不包含从该代码仓库 owner 继承的权限。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体范围内唯一。

查询参数

pageSize integer

返回的最大授权数。未设置或为 0 时默认值为 30；大于 100 的值将被限制为 100。设置 pageToken 时忽略该参数。

pageToken string

来自上一次响应中 next_page_token 的 Opaque cursor。首页请求时留空。

响应字段

grants 数组

直接授予该代码仓库的权限，先按 principal 类型 (群组、所属团队管理员、所属团队成员、用户) 排序，再按 id 排序。若某个 principal 已无法解析为活跃用户、群组或所属团队，则会被略过，因此单页返回的授予记录可能少于 pageSize 条。

grants[].user 对象

用户 principal。user、group 和 teamGroup 中有且仅有一个存在。

grants[].user.id string

用户的公开标识符，前缀为 user_。

grants[].user.email string

用户的电子邮件地址。

grants[].user.displayName string

用户的显示名称：由账户的名字和姓氏以空格连接而成，与产品中显示的名称相同。若账户没有姓名，则省略此字段。

grants[].user.handle string

用户已认领的配置文件 handle，不含 @ 前缀。仅当该配置文件公开可见时才会返回，否则将被省略。

grants[].group 对象

Cursor 组织群组主体。

grants[].group.id string

群组的公开标识符，以 grp_ 为前缀。

grants[].teamGroup 对象

所属团队的内置群组之一，直接在该代码仓库上授予，区别于从所有者继承而来的群组。

grants[].teamGroup.kind string

该授权归属的内置群组。可选值：members、admins。

grants[].permission string

该 principal 对代码仓库拥有的 permission。允许的值：read、write、admin、custom。custom 表示 custom policy，Upsert Repository Grant 不接受该值。

repository 对象

本响应中所有授权所属的代码仓库。字段与 Get Repo 相同。

nextPageToken string

用于获取下一页的不透明游标；没有更多页时为空。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/{ownerSlug}/{repoName}/grants' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "grants": [    {      "group": {        "id": "grp_01k2ja2000e0080000000000n2"      },      "permission": "admin"    },    {      "teamGroup": {        "kind": "admins"      },      "permission": "admin"    },    {      "teamGroup": {        "kind": "members"      },      "permission": "write"    },    {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "jane@acme.dev"      },      "permission": "read"    }  ],  "repository": {    "id": "repo_01k2ja2000e0080000000000q4",    "name": "rocket",    "owner": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    }  },  "nextPageToken": ""}

更新或插入代码仓库授权

POST/v1/origin/repos/{ownerSlug}/{repoName}/grants
Scoperepository:settings:writeAuthInstallation tokenUser access token

设置用户、群组或所属团队群组在某个代码仓库上直接持有的权限，并替换此前直接授予该 principal 的权限。若重复授予 principal 已持有的权限，请求会成功，但不产生任何变更。用户必须是该代码仓库 owner 所属团队或 organization 的 active 成员，群组必须是该 organization 的 active 群组；否则请求将返回 FailedPrecondition (HTTP 400) 。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

请求体

user object

用户 principal。user、group 和 teamGroup 中有且仅有一个存在。

user.id string

用户的公开标识符，前缀为 user_。

user.email string

用户的电子邮件地址。

user.displayName string

用户的显示名称：由账户的名和姓以空格连接而成，与产品中呈现的名称一致。若账户未设置名称，则省略该字段。

user.handle string

用户已认领的配置文件 handle，不含 @ 前缀。仅当该配置文件公开可见时才会返回，否则将被省略。

group 对象

Cursor 组织群组主体。

group.id string

群组的公开标识符，以 grp_ 为前缀。

teamGroup 对象

所属团队的内置群组之一，直接在代码仓库上授予，区别于从所有者继承的群组。

teamGroup.kind string

该授权归属于哪个内置群组。允许的值：members、admins。

permission string 必填

要授予的权限。允许的值：read、write、admin。custom 将返回 InvalidArgument (HTTP 400) ；自定义策略不在此 API 的范围内。

响应字段

user object

用户 principal。user、group 和 teamGroup 中有且仅有一个存在。

user.id string

用户的公开标识符，前缀为 user_。

user.email string

用户的电子邮件地址。

user.displayName string

用户的显示名称：由账户的名和姓以空格连接而成，与产品中显示的名称一致。若账户未设置姓名，则省略该字段。

user.handle string

用户已认领的个人资料 handle，不含 @ 前缀。仅在该个人资料公开可见时存在，否则将被省略。

group 对象

Cursor 组织群组主体。

group.id string

群组的公开标识符，前缀为 grp_。

teamGroup 对象

所属团队的内置群组之一，直接在该代码仓库上授予，与从所有者继承的群组不同。

teamGroup.kind string

该授权归属的内置群组。允许的值：members、admins。

permission string

该 principal 当前对代码仓库拥有的权限。
curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/grants' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "user": {    "id": "user_01k2ja2000e0080000000000c3"  },  "permission": "write"}'

响应结构：

{  "user": {    "id": "user_01k2ja2000e0080000000000c3",    "email": "jane@acme.dev"  },  "permission": "write"}

删除仓库授权

DELETE/v1/origin/repos/{ownerSlug}/{repoName}/grants
Scoperepository:settings:writeAuthInstallation tokenUser access token

移除用户、群组或所属团队群组直接在某个代码仓库上持有的权限。从仓库所有者继承的权限不受影响，因此所属团队群组会回退到其所有者级别的默认值。若移除的权限并非该 principal 直接持有，请求仍会成功，但不会产生任何变更。响应体为空。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体范围内唯一。

请求体

user object

用户 principal。user、group 或 teamGroup 中有且仅有一个存在。

user.id string

用户的公开标识符，前缀为 user_。

user.email string

用户的电子邮件地址。

user.displayName string

用户的显示名称：账户的名与姓以空格连接，与产品中显示的名称一致。账户没有姓名时将省略该字段。

user.handle string

用户已认领的配置文件 handle，不含 @ 前缀。仅在该配置文件公开可见时存在，否则省略。

group object

Cursor 组织群组 principal。

group.id string

群组的公开标识符，前缀为 grp_。

teamGroup object

所属团队的内置群组之一，直接在该仓库上授予，与从所有者继承的授权不同。

teamGroup.kind string

持有该授权的内置群组。允许的值：members、admins。

响应字段

请求成功时不返回响应体。

curl --request DELETE \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/grants' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "group": {    "id": "grp_01k2ja2000e0080000000000n2"  }}'

响应：

204 No Content

列出命名空间授权

GET/v1/origin/owners/{ownerSlug}/grants
Scopenamespace:settings:readAuthInstallation tokenUser access token

列出已获得某个 owner 访问权限的对象：用户、群组，以及所属团队内置的 admin 群组和成员群组。每条授权均包含其在该 owner 下所有仓库上所赋予的权限。针对单个仓库的授权不在此列；请通过 List Repository Grants 读取。

路径参数

ownerSlug string 必填

要列出其授权的所有者的 Slug。

查询参数

pageSize integer

返回的最大 grants 数量。未设置或为 0 时默认值为 30。超过 100 的值会被限制为 100。已设置 pageToken 时忽略该参数。

pageToken string

取自上一次响应中 next_page_token 的不透明游标。请求第一页时留空。

响应字段

grants 数组

本页中的 grants。Admin grants 排在最前；在每个 run 内，grants 先按 principal 类型 (群组、所属团队的 admins、所属团队的成员、用户) 排序，再按 id 排序。若某个 principal 已无法解析为活跃用户、群组或所属团队，则会被省略，因此单页包含的 grants 数量可能少于 pageSize。

grants[].user object

用户 principal。user、group 和 teamGroup 中有且仅有一个存在。

grants[].user.id string

用户的公开标识符，前缀为 user_。

grants[].user.email string

用户的电子邮件地址。

grants[].user.displayName string

用户的显示名称：由账户的名与姓以空格连接而成，与产品中显示的名称一致。账户没有姓名时，该字段将被省略。

grants[].user.handle string

用户已认领的配置文件 handle，不含 @ 前缀。仅当该配置文件公开可见时才会返回，否则将省略。

grants[].group 对象

Cursor 组织群组主体。

grants[].group.id string

群组的公开标识符，前缀为 grp_。

grants[].teamGroup 对象

所属团队的内置群组之一：团队对该 owner 的默认访问权限。

grants[].teamGroup.kind string

该授权归属的内置群组。可选值：members、admins。

grants[].permission string

principal 对该 owner 下所有代码仓库拥有的 permission。允许的值：PERMISSION_READ、PERMISSION_CONTRIBUTOR、PERMISSION_WRITE、PERMISSION_ADMIN、PERMISSION_CUSTOM。PERMISSION_CUSTOM 表示 custom policy，Upsert Namespace Grant 不接受该值。

nextPageToken string

用于获取下一页的不透明游标；没有更多页时为空。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/owners/{ownerSlug}/grants' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "grants": [    {      "group": {        "id": "grp_01k2ja2000e0080000000000n2"      },      "permission": "PERMISSION_ADMIN"    },    {      "teamGroup": {        "kind": "admins"      },      "permission": "PERMISSION_ADMIN"    },    {      "teamGroup": {        "kind": "members"      },      "permission": "PERMISSION_CONTRIBUTOR"    },    {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "jane@acme.dev"      },      "permission": "PERMISSION_WRITE"    }  ],  "nextPageToken": ""}

更新或插入 Namespace Grant

POST/v1/origin/owners/{ownerSlug}/grants
Scopenamespace:settings:writeAuthInstallation tokenUser access token

设置用户、群组或归属团队群组直接在某个 owner 上持有的权限，并替换此前直接授予该 principal 的权限。若重复授予 principal 已持有的权限，请求会成功但不产生任何变更。出现以下情况时，请求返回 FailedPrecondition (HTTP 400) ：该用户不是归属团队或其组织的活跃成员；该群组不是该组织的活跃群组；或该写入操作会导致该 owner 不再有任何 admin。

路径参数

ownerSlug string 必填

所有者 slug。

请求体

user object

用户主体。user、group 和 teamGroup 中有且仅有一个存在。

user.id string

用户的公开标识符，以 user_ 为前缀。

user.email string

用户的电子邮件地址。

user.displayName string

用户的显示名称：由账户的名和姓以空格连接而成，与产品中显示的名称一致。若账户未设置姓名，则省略该字段。

user.handle string

用户已认领的配置文件 handle，不含 @ 前缀。仅当该配置文件公开可见时才会返回，否则将被省略。

group 对象

Cursor 组织群组主体。

group.id string

群组的公开标识符，前缀为 grp_。

teamGroup 对象

所属团队的内置群组之一：团队对该 owner 的默认访问权限。

teamGroup.kind string

该授权归属的内置群组。允许的值：members、admins。

permission string 必填

要授予的权限。可选值：PERMISSION_READ、PERMISSION_CONTRIBUTOR、PERMISSION_WRITE、PERMISSION_ADMIN。其中 PERMISSION_READ、PERMISSION_CONTRIBUTOR 和 PERMISSION_WRITE 会对该 owner 的内部仓库授予相应级别的权限，而 PERMISSION_ADMIN 用于管理 owner 本身。PERMISSION_CUSTOM 将返回 InvalidArgument (HTTP 400) 。

响应字段

user 对象

用户 principal。user、group 和 teamGroup 中有且仅有一个存在。

user.id string

用户的公开标识符，以 user_ 为前缀。

user.email string

用户的电子邮件地址。

user.displayName string

用户的显示名称：由账户的名和姓以空格连接而成，与产品中显示的名称一致。账户没有名称时省略该字段。

user.handle string

用户已认领的配置文件 handle，不含 @ 前缀。仅当该配置文件公开可见时才会返回，否则将被省略。

group 对象

Cursor 组织群组主体。

group.id string

群组的公开标识符，以 grp_ 为前缀。

teamGroup 对象

所属团队的内置群组之一：团队对该 owner 的默认访问权限。

teamGroup.kind string

该授权归属于哪个内置群组。可选值：members、admins。

permission string

该 principal 当前对 owner 名下所有代码仓库拥有的 permission。
curl --request POST \  --url 'https://api.cursor.com/v1/origin/owners/OWNER_SLUG/grants' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "user": {    "id": "user_01k2ja2000e0080000000000c3"  },  "permission": "PERMISSION_WRITE"}'

响应结构：

{  "user": {    "id": "user_01k2ja2000e0080000000000c3",    "email": "jane@acme.dev"  },  "permission": "PERMISSION_WRITE"}

删除 Namespace 授权

DELETE/v1/origin/owners/{ownerSlug}/grants
Scopenamespace:settings:writeAuthInstallation tokenUser access token

移除用户、群组或所属团队群组直接在某个 owner 上持有的权限。per-repository 授权不受影响。若移除的权限 principal 并未直接持有，请求仍会成功，但不产生任何变更；若移除后该 owner 将不再有 admin，则返回 FailedPrecondition (HTTP 400) 。响应体为空。

路径参数

ownerSlug string 必填

Owner slug。

请求体

user object

用户 principal。user、group 或 teamGroup 三者中有且仅有一个存在。

user.id string

用户的公开标识符，前缀为 user_。

user.email string

用户的电子邮件地址。

user.displayName string

用户的 display name：账户的名与姓以空格连接，与产品中显示的名称一致。若账户未设置姓名，则省略该字段。

user.handle string

用户已认领的配置文件 handle，不含 @ 前缀。仅当该配置文件公开可见时存在，否则省略。

group object

Cursor organization group principal。

group.id string

群组的公开标识符，前缀为 grp_。

teamGroup object

所属团队的内置群组之一：即团队对该 owner 的默认访问权限。

teamGroup.kind string

持有该授权的内置群组。允许的值：members、admins。

Response Fields

成功的请求不返回响应体。

curl --request DELETE \  --url 'https://api.cursor.com/v1/origin/owners/OWNER_SLUG/grants' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "group": {    "id": "grp_01k2ja2000e0080000000000n2"  }}'

响应：

204 No Content

标签

标签定义归属于一个代码仓库，并通过名称标识。为 PR 设置标签属于另一项功能；请参阅设置 PR 标签。

列出标签

GET/v1/origin/repos/{ownerSlug}/{repoName}/labels
Scoperepository:labels:readAuthInstallation tokenUser access token

列出代码仓库中定义的标签，按名称排序。

页面 token 与签发它们的代码仓库绑定。将 token 用于其他代码仓库，或使用任何其他格式错误的 token，都会返回 InvalidArgument (HTTP 400) 。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

查询参数

pageSize integer

返回的最大标签数。省略或设为零时，默认值为 30；超过 100 的值将被限制为 100。

pageToken string

来自先前响应 nextPageToken 的不透明游标。获取第一页时省略。

响应字段

labels array

一页标签定义，按名称排序。

labels[].id string

标签的公开标识符。

labels[].name string

标签名称，在代码仓库内唯一。读取和写入端点通过名称标识标签。

labels[].color string

不含前导 # 的六位十六进制颜色值。

labels[].description string

标签描述。标签没有描述时，该字段不存在。

nextPageToken string

用于获取下一页的不透明游标。没有更多结果时为空。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/labels' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "labels": [    {      "id": "lbl_01k2ja2000e0080000000000m1",      "name": "bug",      "color": "d73a4a",      "description": "Something isn't working"    }  ]}

创建标签

POST/v1/origin/repos/{ownerSlug}/{repoName}/labels
Scoperepository:labels:writeAuthInstallation tokenUser access token

在代码仓库中创建标签。

如果名称已被该代码仓库中的其他标签使用，将返回 AlreadyExists (HTTP 409 Conflict) 。如果 color 不是六位十六进制字符、name 超过 50 个字符，或 description 超过 255 个字符，将返回 InvalidArgument (HTTP 400) 。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

请求体

name string 必填

标签名称。会去除首尾空白字符。最大长度：50 个字符。

color string 必填

不含前导 # 的六位十六进制颜色值。大写输入会以小写形式存储。

description string

标签描述。最大长度：255 个字符。

响应字段

id string

标签的公开标识符。

name string

标签名称，在代码仓库内唯一。读取和写入端点通过名称引用标签。

color string

不含前导 # 的六位十六进制颜色值。

description string

标签描述。标签没有描述时不返回此字段。
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": "bug",  "color": "d73a4a",  "description": "Something isn'\''t working"}'

响应结构：

{  "id": "lbl_01k2ja2000e0080000000000m1",  "name": "bug",  "color": "d73a4a",  "description": "Something isn't working"}

获取标签

GET/v1/origin/repos/{ownerSlug}/{repoName}/labels/{labelName}
Scoperepository:labels:readAuthInstallation tokenUser access token

按名称获取单个代码仓库标签。

名称不存在时返回 404。labelName 为空时返回 InvalidArgument (HTTP 400) 。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

labelName string 必填

标签名称。查找前会去除首尾空白字符。

响应字段

id string

标签的公开标识符。

name string

标签名称，在代码仓库内唯一。读取和写入端点通过名称引用标签。

color string

不带前导 # 的六位十六进制颜色值。

description string

标签描述。标签没有描述时不返回此字段。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/labels/LABEL_NAME' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "id": "lbl_01k2ja2000e0080000000000m1",  "name": "bug",  "color": "d73a4a",  "description": "Something isn't working"}

删除标签

DELETE/v1/origin/repos/{ownerSlug}/{repoName}/labels/{labelName}
Scoperepository:labels:writeAuthInstallation tokenUser access token

按名称删除代码仓库标签。响应体为空。

删除标签也会将其从所有分配给它的 PR 中移除。名称不存在时返回 404。labelName 为空时返回 InvalidArgument (HTTP 400) 。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

labelName string 必填

标签名称。查找前会去除首尾空白字符。

响应字段

成功的请求不返回响应体。

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

响应：

204 No Content

更新标签

PATCH/v1/origin/repos/{ownerSlug}/{repoName}/labels/{labelName}
Scoperepository:labels:writeAuthInstallation tokenUser access token

更新由当前名称指定的代码仓库标签。

未提供的字段保持不变；如果请求未提供这三个字段中的任何一个，则返回标签当前的状态。重命名为已被其他标签使用的名称时，返回 AlreadyExists (HTTP 409 Conflict) 。未知的 labelName 返回 404。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

labelName string 必填

当前标签名称。查找前会去除首尾空白字符。

请求体

name string

新标签名称。会去除首尾空白字符。最长 50 个字符。未提供则保持不变。

color string

不含前导 # 的六位十六进制颜色值。未提供则保持不变。

description string

标签描述。最长 255 个字符。未提供则保持不变。

响应字段

id string

标签的公开标识符。

name string

标签名称，在代码仓库内唯一。读取和写入端点均通过名称指定标签。

color string

不含前导 # 的六位十六进制颜色值。

description string

标签描述。标签没有描述时不返回此字段。
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"}'

响应结构：

{  "id": "lbl_01k2ja2000e0080000000000m1",  "name": "bug",  "color": "b60205",  "description": "Something isn't working"}

PR

已关闭或合并的 PR 还可能包含 closedAt、mergedAt 和 mergeCommitSha。将 head.ref 和 base.ref 视为不透明的 Origin 引用 string；它们可能是简短的分支名称，也可能是完全限定的 refs/heads/… 值。

评审 verdict 可以是 approve、request_changes 或 comment。未提交的草稿评审没有 submittedAt。当决定仍有效时，dismissal 不存在。被驳回的评审仍会显示在评审列表中。被较新决定自动取代的评审会附带由服务器生成的消息。

评论会提供用于分组的 thread 引用。回复时，创建评论请求仍接受标量 threadId command 参数。使用 Update Pull Request Thread 解决或重新打开线程。

列出拉取请求

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls
Scoperepository:pull_requests:readAuthInstallation tokenUser access token

列出仓库中的拉取请求，可按源分支、目标分支、作者、创建时间范围和状态筛选。每个拉取请求均包含其分配的标签。

结果可按创建顺序或最后更新时间排序，通过 sortBy 选择，最新的在前。将 direction 设为 asc 可使用相反的顺序。页面令牌会嵌入其生成时的排序和筛选条件，因此在不同的排序或筛选条件下重放的令牌会被拒绝；当任一项更改时请重新开始分页。

路径参数

ownerSlug string 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属所有者实体内唯一。

查询参数

head string

可选的精确分支 (head-ref) 筛选器。省略则列出所有分支。

state string

生命周期筛选。允许的值：open (默认值) 、closed、merged、all。closed 涵盖所有不再处于打开状态的拉取请求，包括已合并的；merged 则仅限已合并的部分。任何其他值都会返回 InvalidArgument (HTTP 400) 。

pageSize 整数

返回结果的最大数量。默认值为 30；最大为 100。

pageToken string

来自上一次响应 nextPageToken 的不透明游标。首页请省略该参数。

author string

可选的作者筛选。传入与此端点在 pullRequests[].author.user.id、pullRequests[].author.app.id 或 pullRequests[].author.serviceAccount.id 中返回的完全相同的公开主体 ID (user_…、app_… 或 sa_…) ，或某个用户的确切电子邮件地址。电子邮件匹配不区分大小写。应用和服务账户没有电子邮件身份，因此只有用户作者可以通过电子邮件来选择。没有拉取请求的作者会返回空列表，解析不到单一用户的电子邮件也会返回空列表。任何其他值 (包括共享的 origin-cursor-managed-actor ID) 都会返回 InvalidArgument (HTTP 400) 。

base string

可选的精确基础分支筛选器。接受短名称 (main) 或完全限定的引用 (refs/heads/main) 。省略以在所有基础分支中列出。

direction string

按 sortBy 指定的方向排序。"desc" 是默认值：当 sortBy=created 时，最近创建的最先返回；当 sortBy=updated 时，最近更新的最先返回。"asc" 则相反。任何其他值会返回 InvalidArgument (HTTP 400) 。

since string

可选的创建时间下限 (包含) ，采用 RFC 3339 时间戳格式，例如 2026-08-01T00:00:00Z。仅返回在该时刻或之后创建的拉取请求。格式错误的时间戳将返回 InvalidArgument (HTTP 400) 。

until string

可选的创建时间上限 (包含该时间点) ，格式与 since 相同，均为 RFC 3339。仅返回在该时刻或之前创建的拉取请求。格式错误的时间戳会返回 InvalidArgument (HTTP 400) 。

sortBy string

排序键。允许的值：created (创建顺序，默认) 或 updated (最后更新时间) 。任何其他值将返回 InvalidArgument (HTTP 400) 。

响应字段

pullRequests 数组

PullRequest 快照页面；响应编号和版本号为 JSON 字符串。

pullRequests[].id string

Stable Origin 拉取请求标识符。

pullRequests[].number string

以 JSON 字符串编码的仓库本地拉取请求编号。

pullRequests[].state string

拉取请求状态：打开或关闭。已合并的拉取请求为关闭状态，且 merged 设置为 true。

pullRequests[].draft boolean

PR 是否为草稿。

pullRequests[].merged 布尔值

PR 是否已合并。

pullRequests[].title string

PR 标题。

pullRequests[].body string

PR 描述正文。

pullRequests[].head 对象

变更的源端——要合并进来的内容。

pullRequests[].head.ref string

Origin 记录的此端所指向的引用。

pullRequests[].head.sha string

此端在该变更最新版本的提示提交 SHA。

pullRequests[].base 对象

该变更的目标端——即合并到的位置。

pullRequests[].base.ref string

Origin 记录的此端所指向的引用。

pullRequests[].base.sha 字符串

此端在该变更最新版本中的末端提交 SHA。

pullRequests[].author 对象

创建该拉取请求的公开主体。

pullRequests[].author.user 对象

执行操作的主体的用户变体。用户执行该操作时设置。

pullRequests[].author.user.id string

用户的公开标识符。

pullRequests[].author.user.email string

用户的电子邮件地址。在存在用户变体时始终设置。

pullRequests[].author.user.displayName string

用户的显示名称：账户的名字和姓氏以空格连接，与产品显示的名称相同。若账户没有姓名则省略。

pullRequests[].author.user.handle string

用户已认领的个人资料用户名，不含 @ 前缀。仅在该个人资料公开可见时返回；否则省略。

pullRequests[].author.app 对象

操作主体的应用变体。由应用执行该操作时设置。

pullRequests[].author.app.id string

应用的公开标识符。

pullRequests[].author.app.displayName 字符串

应用已注册的显示名称。在应用无法解析或属于 Cursor 第一方托管主体时省略。

pullRequests[].author.serviceAccount 对象

操作主体的服务账户变体。由服务账户执行该操作时设置。

pullRequests[].author.serviceAccount.id string

服务帐户的公开标识符。

pullRequests[].createdAt string

RFC 3339 拉取请求创建时间戳。

pullRequests[].updatedAt string

最新拉取请求更新的 RFC 3339 时间戳。

pullRequests[].closedAt string

RFC 3339 格式的关闭时间戳；可能出现在已关闭或已合并的拉取请求中。

pullRequests[].mergedAt string

RFC 3339 格式的合并时间戳；可能出现在已合并的拉取请求上。

pullRequests[].mergeCommitSha string

合并提交 SHA；可能在合并后出现。

pullRequests[].additions 整数

当前 PR 版本中新增的代码行。

pullRequests[].deletions 整数

当前拉取请求版本中已删除的行。

pullRequests[].changedFiles 整数

当前拉取请求当前版本中已更改的文件数。

pullRequests[].labels 数组

当前分配给该拉取请求的标签，按名称排序。若未分配则为空。

pullRequests[].labels[].id string

标签的公开标识符。

pullRequests[].labels[].name string

标签名称，在仓库内唯一。在写入端点中通过名称引用该标签。

pullRequests[].labels[].color string

不带前导 # 的六位十六进制颜色。

pullRequests[].labels[].description string

标签描述。标签未设置描述时不返回此字段。

pullRequests[].version 对象

当前编号的拉取请求版本及其 head/base SHA。

pullRequests[].version.number string

编码为 JSON 字符串的单调递增 PR 版本号。

pullRequests[].version.headSha string

此拉取请求版本记录的 Head SHA。

pullRequests[].version.baseSha string

此 PR 版本记录的 Base SHA。

pullRequests[].version.createdAt string

此拉取请求版本创建时的 RFC 3339 时间戳。

nextPageToken string

列表响应返回的不透明续页令牌；空字符串表示没有下一页。请勿检查或构造该令牌，并在代码仓库或筛选条件更改时重新开始分页。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "pullRequests": [    {      "id": "pr_01k2ja2000e0080000000000d4",      "number": "17",      "state": "open",      "draft": false,      "merged": false,      "title": "Add launch telemetry",      "body": "Adds structured launch telemetry to the ignition path.",      "head": {        "ref": "add-telemetry",        "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4"      },      "base": {        "ref": "main",        "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"      },      "author": {        "user": {          "id": "user_01k2ja2000e0080000000000c3",          "email": "jane@acme.dev"        }      },      "createdAt": "2026-08-01T09:30:00Z",      "updatedAt": "2026-08-02T14:45:00Z",      "additions": 128,      "deletions": 46,      "changedFiles": 5,      "labels": [        {          "id": "lbl_01k2ja2000e0080000000000m1",          "name": "bug",          "color": "d73a4a",          "description": "Something isn't working"        }      ],      "version": {        "number": "3",        "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",        "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",        "createdAt": "2026-08-01T09:30:00Z"      }    }  ]}

获取 PR

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}
Scoperepository:pull_requests:readAuthInstallation tokenUser access token

返回单个 PR，包括其已分配的标签。

已关闭或已合并的拉取请求还可能包含 closedAt、mergedAt 和 mergeCommitSha。将 head.ref 和 base.ref 视为不透明的 Origin 引用字符串；它们可以是短分支名称，也可以是完全限定的 refs/heads/… 值。

路径参数

ownerSlug 字符串 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

pullNumber 字符串 必填

响应字段

id string

Stable Origin 拉取请求标识符。

number string

代码仓库内的拉取请求编号，以 JSON 字符串编码。

state string

拉取请求状态：打开或关闭。已合并的拉取请求为关闭状态，且 merged 字段为 true。

draft boolean

该 PR 是否为草稿。

merged boolean

PR 是否已合并。

title string

PR 标题。

body string

PR 描述正文。

head 对象

变更的源端——即要合并的内容。

head.ref string

按 Origin 的记录，此端指向的引用。

head.sha string

此端在该变更最新版本中的末端提交 SHA。

base 对象

该变更的目标端 —— 要合并到的分支。

base.ref string

按 Origin 的记录，此端所指向的引用。

base.sha string

此端在该变更最新版本中的末端提交 SHA。

author 对象

创建并打开此拉取请求的公共主体。

author.user 对象

操作主体的用户变体。用户执行该操作时设置。

author.user.id string

用户的公开标识符。

author.user.email string

用户的电子邮件地址。存在用户变体时始终设置。

author.user.displayName string

用户显示名称：账户的名字和姓氏以空格连接，与产品中呈现的名称相同。账户没有名称时省略。

author.user.handle string

用户已认领的个人资料 Handle (不含 @ 前缀) 。仅在该个人资料公开可见时提供；否则省略。

author.app 对象

操作主体的应用变体。在应用执行该操作时设置。

author.app.id string

应用的公开标识符。

author.app.displayName string

应用的已注册显示名称。应用无法解析时，以及在 Cursor 的第一方托管 actor 上，将省略此字段。

author.serviceAccount 对象

操作主体的服务帐号变体。由服务帐号执行该操作时设置。

author.serviceAccount.id string

服务账户的公开标识符。

createdAt string

RFC 3339 拉取请求创建时间戳。

updatedAt string

最新拉取请求更新的 RFC 3339 时间戳。

closedAt string

RFC 3339 格式的关闭时间戳；可能出现在已关闭或已合并的拉取请求中。

mergedAt string

RFC 3339 合并时间戳；可能出现在已合并的拉取请求中。

mergeCommitSha 字符串

合并提交的 SHA；可能在合并后出现。

additions 整数

当前拉取请求版本中新增的行。

deletions 整数

当前 PR 版本中已删除的行。

changedFiles 整数

当前 PR 版本中已修改的文件数量。

labels array

当前分配给该拉取请求的标签，按名称排序。若未分配则为空。

labels[].id string

标签的公共标识符。

labels[].name string

标签名称，在仓库中唯一。写入端点使用名称来定位该标签。

labels[].color string

不含前导 # 的六位十六进制颜色值。

labels[].description string

标签描述。若标签无描述，则不返回此字段。

version 对象

当前指定编号的 Pull Request 版本及其 head/base SHA。

version.number string

单调递增的拉取请求版本号，编码为 JSON 字符串。

version.headSha string

此拉取请求版本记录的 Head SHA。

version.baseSha string

此 PR 版本记录的基准 SHA。

version.createdAt string

此 PR 版本创建时间的 RFC 3339 时间戳。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "id": "pr_01k2ja2000e0080000000000d4",  "number": "17",  "state": "open",  "draft": false,  "merged": false,  "title": "Add launch telemetry",  "body": "Adds structured launch telemetry to the ignition path.",  "head": {    "ref": "add-telemetry",    "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4"  },  "base": {    "ref": "main",    "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"  },  "author": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  },  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z",  "additions": 128,  "deletions": 46,  "changedFiles": 5,  "labels": [    {      "id": "lbl_01k2ja2000e0080000000000m1",      "name": "bug",      "color": "d73a4a",      "description": "Something isn't working"    }  ],  "version": {    "number": "3",    "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",    "createdAt": "2026-08-01T09:30:00Z"  }}

创建拉取请求

POST/v1/origin/repos/{ownerSlug}/{repoName}/pulls
Scoperepository:pull_requests:writeAuthInstallation tokenUser access token

创建一个从 head 合并到 base 的拉取请求。

可选参数 parent_pull_number 可将此更改叠加到同一代码仓库中另一个处于开放或草稿状态的 PR。

title 超过 256 个字符，或 body 超过 65,536 个字符时，将返回 InvalidArgument (HTTP 400) 。两项限制均按 Unicode 代码点计算。

若 head 与 base 没有共同历史，则返回 InvalidArgument (HTTP 400) ，并且不会创建任何内容。如果后续的推送使某个打开的拉取请求的 head 与其 base 不再相交，Origin 会关闭该拉取请求并发送 pull_request.closed；随后相关的推送不会重新打开该请求。

路径参数

ownerSlug 字符串 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

请求体

title string 必填

PR 标题。最多 256 个字符。

body string

PR 正文/描述。可为空。最大长度：65,536 个字符。

head string 必填

源分支名称 (变更的 HEAD) 。调用时必须能在仓库中解析。

base string 必填

目标分支名称 (更改将合并到的分支) 。必须指定调用时仓库中已存在的分支。若为提交 SHA、标签名称或不存在的分支，则返回 InvalidArgument (HTTP 400) 。

draft 布尔值

为 true 时，创建为草稿；为 false 或省略时，创建为开放状态 (可供评审) 。

parentPullNumber string

可选的父拉取请求编号，用于在同一仓库将此更改叠加到另一个打开或草稿状态的更改上时使用。

响应字段

id string

Stable Origin 拉取请求标识符。

number string

以 JSON 字符串编码的仓库本地拉取请求编号。

state string

PR 状态：打开或关闭。已合并的 PR 为关闭，且 merged 设置为 true。

draft 布尔值

PR 是否为草稿。

merged boolean

拉取请求是否已合并。

title string

PR 标题。

body string

PR 描述正文。

head 对象

变更的源端 —— 即将合并进来的内容。

head.ref string

根据 Origin 的记录，此端引用所指向的对象。

head.sha string

此侧在该变更最新版本的提交 SHA。

base 对象

变更的目标分支 —— 要合并到的分支。

base.ref string

根据 Origin 的记录，此端引用所指向的对象。

base.sha string

此侧在该变更最新版本的提交 SHA。

author 对象

创建该拉取请求的公共主体。

author.user 对象

执行操作的主体为用户时的变体。用户执行操作时设置。

author.user.id string

用户的公开标识符。

author.user.email string

用户的电子邮件地址。在存在用户变体时始终设置。

author.user.displayName string

用户的显示名称：账户的名字与姓氏以空格连接，与产品显示的名称相同。若账户没有名称则省略。

author.user.handle string

用户已认领的个人资料句柄，不含 @ 前缀。仅在该个人资料公开可见时返回；否则省略。

author.app 对象

actor 的 app 变体。当 app 执行动作时设置。

author.app.id string

应用的公开标识符。

author.app.displayName string

应用已注册的显示名称。当应用无法解析或为 Cursor 第一方托管的主体时将被省略。

author.serviceAccount object

actor 的 service account 变体。当由 service account 执行该操作时设置此字段。

author.serviceAccount.id string

服务账户的公开标识符。

createdAt string

RFC 3339 格式的拉取请求创建时间戳。

updatedAt string

最新拉取请求更新的 RFC 3339 时间戳。

closedAt string

RFC 3339 格式的关闭时间戳；可能出现在已关闭或已合并的拉取请求中。

mergedAt string

RFC 3339 合并时间戳；可能显示在已合并的拉取请求上。

mergeCommitSha string

合并提交的 SHA；可能出现在合并之后。

additions 整数

当前 PR 版本新增的行。

deletions 整数

当前 PR 版本中已删除的行。

changedFiles 整数

当前 PR 版本中修改的文件数量。

labels 数组

当前分配给拉取请求的标签，按名称排序。若未分配则为空。

labels[].id string

标签的公开标识符。

labels[].name string

标签名称，在仓库中必须唯一。写入端点通过名称引用该标签。

labels[].color string

不带前导 # 的六位十六进制颜色。

labels[].description string

标签描述。如标签无描述则不返回此字段。

version object

当前带编号的拉取请求版本及其 head/base SHA。

version.number string

单调递增的拉取请求版本号，以 JSON 字符串形式编码。

version.headSha string

此拉取请求版本记录的 Head SHA。

version.baseSha string

此拉取请求版本记录的基础 SHA。

version.createdAt string

该拉取请求版本创建时间的 RFC 3339 时间戳。
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": "Add launch telemetry",  "body": "Adds structured launch telemetry to the ignition path.",  "head": "add-telemetry",  "base": "main",  "draft": false}'

响应结构：

{  "id": "pr_01k2ja2000e0080000000000d4",  "number": "17",  "state": "open",  "draft": false,  "merged": false,  "title": "Add launch telemetry",  "body": "Adds structured launch telemetry to the ignition path.",  "head": {    "ref": "add-telemetry",    "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4"  },  "base": {    "ref": "main",    "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"  },  "author": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  },  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z",  "additions": 128,  "deletions": 46,  "changedFiles": 5,  "labels": [    {      "id": "lbl_01k2ja2000e0080000000000m1",      "name": "bug",      "color": "d73a4a",      "description": "Something isn't working"    }  ],  "version": {    "number": "3",    "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",    "createdAt": "2026-08-01T09:30:00Z"  }}

更新拉取请求

PATCH/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}
Scoperepository:pull_requests:writeAuthInstallation tokenUser access token

更新 PR 的标题、正文、目标分支和/或生命周期状态。

省略的字段保持不变。存在的字段按以下顺序应用：metadata，然后 reopen/草稿/准备审查，然后 base，最后 close。close 在最后运行，因此同一请求的重新定向仍可看到处于打开状态的更改；reopen 在 base 之前运行，因此已关闭的拉取请求可以重新定向。如果后续步骤失败，前面的步骤可能已被提交。

title 长于 256 个字符，或 body 长于 65,536 个字符，则返回 InvalidArgument (HTTP 400) 。这两个限制均按 Unicode 代码点计数。

路径参数

ownerSlug string 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

pullNumber string 必填

请求体

title string

新标题。未填写的字段保持不变。最大长度：256 个字符。

body string

新的正文/描述。空字符串会清除正文。最大长度：65,536 个字符。

state string

"open" 或 "closed"。"closed" 会关闭拉取请求。未带 draft: true 的 "open" 会将其标记为可供审查，包括发布已有草稿。已合并状态不可写。请使用 MergePullRequest。

draft 布尔值

true 将拉取请求标记为草稿；false 将其标记为可供审查 (若当前已关闭，则会重新打开) 。当 state 为 "closed" 时忽略。

base string

新的基准分支。重新定位该拉取请求；当新的基准是另一项更改的 head (或默认分支) 时，可以更新分支栈的父子关系。必须指定调用时仓库中已存在的分支；若为提交 SHA、标签名或不存在的分支，则返回 InvalidArgument (HTTP 400) 。

响应字段

id string

Stable Origin 拉取请求标识符。

number string

以 JSON 字符串编码的仓库本地拉取请求编号。

state string

拉取请求状态：打开或已关闭。已合并的拉取请求为已关闭，且 merged 设置为 true。

draft 布尔值

该 PR 是否为草稿。

merged 布尔值

PR 是否已合并。

title string

PR 标题。

body string

拉取请求描述正文。

head 对象

变更的源端——即将合并进来的内容。

head.ref string

Origin 记录的此端引用所指向的对象。

head.sha string

此变更最新版本中该方的提交 SHA。

base 对象

变更的目标端 —— 即合并到的对象。

base.ref string

Origin 记录的此端引用所指向的对象。

base.sha string

此变更最新版本中该方的提交 SHA。

author 对象

发起该拉取请求的公共主体。

author.user 对象

操作主体的用户变体。由用户执行该操作时设置。

author.user.id string

用户的公开标识符。

author.user.email string

用户的电子邮件地址。存在用户变体时始终设置。

author.user.displayName string

用户的显示名称：账户的名和姓以空格连接，与产品展示的名称相同。若账户没有名称则省略。

author.user.handle string

用户已认领的个人资料用户名，不含 @ 前缀。仅在该个人资料公开可见时提供；否则省略。

author.app 对象

行为主体的应用变体。当某个应用执行该操作时设置。

author.app.id string

应用的公开标识符。

author.app.displayName string

应用的已注册显示名称。 当应用无法解析或在 Cursor 的第一方托管主体上时将被省略。

author.serviceAccount 对象

行为主体的服务帐户变体。服务帐户执行该操作时设置。

author.serviceAccount.id string

服务帐户的公开标识符。

createdAt string

RFC 3339 格式的 PR 创建时间戳。

updatedAt string

最新拉取请求更新的 RFC 3339 时间戳。

closedAt string

RFC 3339 格式的关闭时间戳；可能出现在已关闭或已合并的拉取请求中。

mergedAt string

RFC 3339 合并时间戳；可能出现在已合并的拉取请求中。

mergeCommitSha string

合并提交的 SHA；可能在合并后出现。

additions 整数

当前 PR 版本中新增的行。

deletions 整数

当前拉取请求版本中已删除的行。

changedFiles 整数

当前 PR 版本中已更改的文件数。

labels 数组

当前分配给拉取请求的标签，按名称排序。未分配时为空。

labels[].id string

标签的公开标识符。

labels[].name string

标签名称，在仓库内唯一。写入端点通过名称引用该标签。

labels[].color string

不含前导 # 的六位十六进制颜色值。

labels[].description string

标签描述。若标签无描述则不返回此字段。

version 对象

当前带编号的拉取请求版本及其 head/base SHA。

version.number string

编码为 JSON 字符串的单调递增的拉取请求版本号。

version.headSha string

此拉取请求版本记录的 Head SHA。

version.baseSha string

此 PR 版本记录的基准 SHA。

version.createdAt string

此 PR 版本创建时的 RFC 3339 时间戳。
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": "Add launch telemetry",  "body": "Adds structured launch telemetry to the ignition path.",  "state": "open",  "draft": false,  "base": "main"}'

响应结构：

{  "id": "pr_01k2ja2000e0080000000000d4",  "number": "17",  "state": "open",  "draft": false,  "merged": false,  "title": "Add launch telemetry",  "body": "Adds structured launch telemetry to the ignition path.",  "head": {    "ref": "add-telemetry",    "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4"  },  "base": {    "ref": "main",    "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"  },  "author": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  },  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z",  "additions": 128,  "deletions": 46,  "changedFiles": 5,  "labels": [    {      "id": "lbl_01k2ja2000e0080000000000m1",      "name": "bug",      "color": "d73a4a",      "description": "Something isn't working"    }  ],  "version": {    "number": "3",    "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",    "createdAt": "2026-08-01T09:30:00Z"  }}

列出拉取请求评论

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/comments
Scoperepository:pull_requests:reviews:readAuthInstallation tokenUser access token

按时间顺序列出拉取请求中的每条评论，可选择限定在某个创建时间窗口内。每条评论都包含其完整线程：id、差异锚点和解决状态。无需发起第二个请求，即可按 thread.id 对扁平响应进行分组。

页面 token 内嵌了签发时所依据的筛选条件，因此在不同筛选条件下重放的 token 会被拒绝；筛选条件发生更改时请重新开始分页。

路径参数

ownerSlug string 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

pullNumber string 必填

查询参数

pageSize 整数

返回的评论数量上限。默认值为 30；最大为 100。

pageToken string

来自上一次响应 nextPageToken 的不透明游标。请求第一页时请省略。

since string

可选的评论创建时间下限 (含该时刻) ，采用 RFC 3339 时间戳格式，例如 2026-08-01T00:00:00Z。仅返回在该时刻或之后创建的评论。时间戳格式错误时返回 InvalidArgument (HTTP 400) 。

until string

可选的评论创建时间上限 (含该时刻) ，采用与 since 相同的 RFC 3339 格式。仅返回在该时刻或之前创建的评论。时间戳格式不正确时返回 InvalidArgument (HTTP 400) 。

threadIds 数组

可选的线程 ID，用于将列表限制为这些线程中的评论。省略则返回拉取请求中的所有评论。重复项会被忽略，因此 20 的限制适用于不同的 ID。列表过长或 ID 为空时，会返回 InvalidArgument (HTTP 400) 。

响应字段

comments 数组

将可见的一般评论和行内评论作为一个按时间顺序的平面列表显示；按 thread.id 分组。

comments[].id string

稳定的 PR 评论标识符。

comments[].thread 对象

该评论所属的线程，包括其差异锚点和解决状态。

comments[].thread.id string

线程的稳定标识。按此值将同一讨论中的评论分组。

comments[].thread.version 对象

创建该线程时所对应的拉取请求版本，包括其 head 和 base SHA。锚点固定在此版本上，不会随拉取请求增加版本而移动。

comments[].thread.version.number string

以 JSON 字符串编码的单调递增拉取请求版本号。

comments[].thread.version.headSha string

此拉取请求版本记录的 Head SHA。

comments[].thread.version.baseSha string

此 PR 版本记录的 base SHA。

comments[].thread.version.createdAt string

该拉取请求版本的 RFC 3339 创建时间戳。

comments[].thread.path string

线程的 diff 锚点所在文件路径。一般讨论线程为空。

comments[].thread.side string

锚点位于 diff 的哪一侧。允许的值：left、right。常规讨论线程中不设置。

comments[].thread.startLine 整数

文件 side 版本中锚定范围的起始行。文件级和一般讨论线程为 0。

comments[].thread.endLine 整数

锚定范围的最后一行 (含该行) 。当锚点为单行或没有行范围时为 0。

comments[].thread.resolvedAt string

线程被解决时的 RFC 3339 时间戳。线程处于打开状态时未设置。

comments[].thread.createdAt string

RFC 3339 线程创建时间戳。

comments[].thread.updatedAt string

线程最近一次更新的 RFC 3339 时间戳。

comments[].body string

评论内容。

comments[].author 对象

创建该评论的公开主体。

comments[].author.user 对象

操作主体的用户变体。用户执行该操作时设置。

comments[].author.user.id string

用户的公开标识符。

comments[].author.user.email string

用户的电子邮件地址。若存在用户变体，则始终设置。

comments[].author.user.displayName string

用户的显示名称：账户的名和姓以空格连接，与产品中呈现的名称相同。账户没有名称时省略。

comments[].author.user.handle string

用户已认领的个人资料用户名，不含 @ 前缀。仅在该资料公开可见时提供；否则省略。

comments[].author.app 对象

操作主体的应用变体。由应用执行该操作时设置。

comments[].author.app.id string

应用的公开标识符。

comments[].author.app.displayName string

应用的注册显示名称。当应用无法解析或在 Cursor 的第一方托管主体上时省略。

comments[].author.serviceAccount 对象

操作主体的服务账号变体。由服务账号执行该操作时设置。

comments[].author.serviceAccount.id string

服务账号的公开标识符。

comments[].createdAt string

RFC 3339 注释创建时间戳。

comments[].updatedAt string

最新评论编辑的 RFC 3339 时间戳。

pullRequest 对象

随评论页面一同返回的容器 PullRequestReference。

pullRequest.id string

稳定的拉取请求标识符。

pullRequest.number string

以 JSON 字符串编码的仓库内拉取请求编号。

pullRequest.repository 对象

拉取请求的仓库容器引用。

pullRequest.repository.id string

容器引用中的仓库标识符。

pullRequest.repository.name string

容器引用中的存储库名称。

pullRequest.repository.owner 对象

代码仓库的所有者引用。

pullRequest.repository.owner.slug string

用于与所有者 ID 一起标识仓库所有者的面向 URL 的所有者 slug。

pullRequest.repository.owner.id string

Origin 所有者标识符。

pullRequest.repository.owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

nextPageToken string

用于获取下一页的不透明游标；当没有更多评论时为空。
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'

响应结构：

{  "comments": [    {      "id": "cmt_01k2ja2000e0080000000000e5",      "thread": {        "id": "cth_01k2ja2000e0080000000000s6",        "version": {          "number": "3",          "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",          "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",          "createdAt": "2026-08-01T09:30:00Z"        },        "path": "src/telemetry/retry.ts",        "side": "right",        "startLine": 42,        "endLine": 45,        "createdAt": "2026-08-01T09:30:00Z",        "updatedAt": "2026-08-02T14:45:00Z"      },      "body": "Should the retry budget be configurable?",      "author": {        "user": {          "id": "user_01k2ja2000e0080000000000c3",          "email": "jane@acme.dev"        }      },      "createdAt": "2026-08-01T09:30:00Z",      "updatedAt": "2026-08-02T14:45:00Z"    }  ],  "pullRequest": {    "id": "pr_01k2ja2000e0080000000000d4",    "number": "17",    "repository": {      "id": "repo_01k2ja2000e0080000000000q4",      "name": "rocket",      "owner": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      }    }  }}

获取 Pull Request 注释

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/comments/{commentId}
Scoperepository:pull_requests:reviews:readAuthInstallation tokenUser access token

根据稳定的 Origin ID 返回单条拉取请求评论。位于已授权仓库之外的评论，或调用方不可见的待审评论，将返回 404。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName 字符串 必填

仓库名称，在拥有者实体内唯一。

commentId string 必填

响应字段

id string

稳定的 PR 评论标识符。

thread object

此评论所属的线程，包括其 diff 锚点和解决状态。

thread.id string

线程的稳定标识。可按该值将同一讨论中的评论分组。

thread.version object

该线程所针对的拉取请求版本，包括其 head 和 base SHA。锚点固定在该版本，不会随着拉取请求新增版本而移动。

thread.version.number string

编码为 JSON 字符串的单调递增拉取请求版本号。

thread.version.headSha string

此拉取请求版本捕获的 Head SHA。

thread.version.baseSha string

此 PR 版本记录的基准 SHA。

thread.version.createdAt string

此 PR 版本创建时间的 RFC 3339 时间戳。

thread.path string

该线程 diff 锚点所在的文件路径。综合讨论线程该字段为空。

thread.side string

锚点位于 diff 的哪一侧。允许的值：left、right。常规讨论线程不设置此字段。

thread.startLine integer

文件 side 版本中锚定范围的起始行。文件级别和常规讨论线程为 0。

thread.endLine integer

锚定范围包含的最后一行。当锚点为单行或没有行范围时为 0。

thread.resolvedAt string

线程解决时的 RFC 3339 时间戳。线程处于打开状态时未设置。

thread.createdAt string

RFC 3339 线程创建时间戳。

thread.updatedAt string

最近一次线程更新的 RFC 3339 时间戳。

body string

评论内容。

author object

发布该评论的公众主体。

author.user object

行为主体的用户变体。用户执行该操作时设置。

author.user.id string

用户的公开标识符。

author.user.email string

该用户的电子邮件地址。存在 user 变体时始终设置。

author.user.displayName string

用户显示名称：账户的名字和姓氏以空格连接，与产品中显示的名称相同。若账户没有名称则省略。

author.user.handle string

用户已认领的个人资料用户名，不含 @ 前缀。仅在该个人资料公开可见时存在；否则省略。

author.app object

行为主体的应用变体。仅在应用执行该操作时设置。

author.app.id string

应用的公开标识符。

author.app.displayName string

应用的注册显示名称。当应用无法解析或为 Cursor 的第一方托管主体时省略。

author.serviceAccount object

行为主体的服务账号变体。当操作由服务账号执行时设置。

author.serviceAccount.id string

服务账户的公开标识符。

createdAt string

评论创建时间的 RFC 3339 时间戳。

updatedAt string

最近一次编辑评论的 RFC 3339 时间戳。
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'

响应结构：

{  "id": "cmt_01k2ja2000e0080000000000e5",  "thread": {    "id": "cth_01k2ja2000e0080000000000s6",    "version": {      "number": "3",      "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",      "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",      "createdAt": "2026-08-01T09:30:00Z"    },    "path": "src/telemetry/retry.ts",    "side": "right",    "startLine": 42,    "endLine": 45,    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T14:45:00Z"  },  "body": "Should the retry budget be configurable?",  "author": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  },  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z"}

创建拉取请求评论

POST/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/comments
Scoperepository:pull_requests:reviews:writeAuthInstallation tokenUser access token

在 Origin 拉取请求上创建评论。该评论精确地针对以下四种情况之一：threadId — 回复现有线程 (适用于常规讨论和内联) ；inline — 在拉取请求版本的 diff 中针对某个行范围新建一个附着线程；file — 在该 diff 中针对整个文件新建一个线程；如果三者均未提供，则新建一个常规讨论线程。正文超过 65,536 个字符将被拒绝并返回 InvalidArgument (HTTP 400) 。

inline 锚点必须引用该版本的 diff。path 必须是该 diff 的一部分，且该处的 side 必须有内容，因此在新增文件上将 left 设为锚点或在已删除文件上将 right 设为锚点会被拒绝并返回 InvalidArgument (HTTP 400) 。修改文件的任意一行都可作为锚点，且范围不限于 diff 的 hunks。范围必须与锚定侧的文件相符，left 读取的是 base 提交处的文件，right 读取的是 head 处的文件：超出最后一行的范围会被拒绝并返回 InvalidArgument (HTTP 400) 。当锚点无效时，Origin 不会退回为一般讨论评论。

file 锚点仅包含路径。Origin 会根据文件的变更类型确定侧：已删除文件使用 base 版本，其他情况使用 head 版本，并通过 thread.side 返回。删除时发送已删除的路径，其他所有变更发送 head 路径。diff 之外的路径会被拒绝并返回 InvalidArgument (HTTP 400) ，重命名文件重命名前的源路径也会被拒绝。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

pullNumber string 必填

请求体

body string 必填

评论内容。最大长度：65,536 个字符，按 Unicode 代码点计算。

threadId string

要回复的现有线程 ID。省略以开启新线程。不能与 versionNumber 一起使用。

inline 对象

新建内联线程的 Diff 锚点。不能与 threadId 一起使用。

inline.path string 必填

PR 版本的 diff 中的文件路径。

inline.side string 必填

锚点所在的 diff 侧。允许的取值：left 表示文件的 base 版本，right 表示 head 版本。

inline.startLine integer 必填

文件 side 版本中锚定范围的首行 (从 1 开始计数) 。该范围不得超出该文件的末尾。

inline.endLine 整数

锚定范围的最后一行 (包含) 。必须大于或等于 startLine。对于单行锚点可省略。

file 对象

在拉取请求版本的 diff 中，为整个文件创建新的文件级线程的锚点。不能与 threadId 或 inline 一起使用。

file.path string 必填

PR 版本的 diff 中的文件路径：删除时为已删除的路径，否则为 head 路径。

versionNumber string

创建新线程时要针对的拉取请求版本号。0 或未设置表示调用时的最新版本。仅对新线程有意义。

响应字段

id string

稳定的拉取请求评论标识符。

thread object

该评论所属的线程。回复仅包含线程 ID，新建的一般讨论线程包含 ID 与时间戳；新建的内联线程包含完整锚点。有关完整的线程状态，请参阅获取拉取请求评论或列出拉取请求评论。

thread.id string

线程的稳定标识。根据此值将同一讨论中的评论分组。

thread.version 对象

该线程所针对的拉取请求版本，包括其 head 和 base SHA。锚点固定在此版本，不会随着拉取请求新增版本而移动。

thread.version.number string

编码为 JSON 字符串的单调递增拉取请求版本号。

thread.version.headSha string

此拉取请求版本记录的 Head SHA。

thread.version.baseSha string

此拉取请求版本记录的基础 SHA。

thread.version.createdAt string

该拉取请求版本创建时间的 RFC 3339 时间戳。

thread.path string

线程 diff 锚点所在的文件路径。常规讨论线程则为空。

thread.side string

锚点位于 diff 的哪一侧。允许的值：left、right。常规讨论线程不设置此字段。

thread.startLine 整数

文件的 side 版本中锚定范围的第一行。文件级和常规讨论线程为 0。

thread.endLine 整数

锚定范围包含的最后一行。若锚点为单行或没有行范围，则为 0。

thread.resolvedAt string

线程被标记为已解决时的 RFC 3339 时间戳。线程处于打开状态时未设置。

thread.createdAt string

RFC 3339 线程创建时间戳。

thread.updatedAt string

线程最近一次更新时间的 RFC 3339 时间戳。

body string

评论内容。

author object

撰写该评论的公开主体。

author.user object

操作主体的用户变体。用户执行该操作时设置。

author.user.id string

用户的公开标识符。

author.user.email string

用户的电子邮件地址。用户变体存在时始终设置。

author.user.displayName string

用户显示名称：账户的名和姓之间以空格连接，与产品中显示的名称相同。账户没有名称时省略。

author.user.handle string

用户已认领的资料用户名，不含 @ 前缀。仅在该资料公开可见时提供；否则省略。

author.app object

操作主体的应用变体。应用执行该操作时设置。

author.app.id string

应用的公开标识符。

author.app.displayName string

应用已注册的显示名称。当应用无法解析或在 Cursor 的第一方托管主体上时将省略。

author.serviceAccount 对象

操作主体的服务帐户变体。在服务帐户执行该操作时设置。

author.serviceAccount.id string

服务账户的公开标识符。

createdAt string

RFC 3339 评论创建时间戳。

updatedAt string

评论最近一次编辑的 RFC 3339 时间戳。
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": "Should the retry budget be configurable?"}'

响应结构：

{  "id": "cmt_01k2ja2000e0080000000000e5",  "thread": {    "id": "cth_01k2ja2000e0080000000000s6",    "version": {      "number": "3",      "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",      "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",      "createdAt": "2026-08-01T09:30:00Z"    },    "path": "src/telemetry/retry.ts",    "side": "right",    "startLine": 42,    "endLine": 45,    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T14:45:00Z"  },  "body": "Should the retry budget be configurable?",  "author": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  },  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z"}

更新 Pull Request 评论

PATCH/v1/origin/repos/{ownerSlug}/{repoName}/pulls/comments/{commentId}
Scoperepository:pull_requests:reviews:writeAuthInstallation tokenUser access token

根据稳定的 Origin id 更新拉取请求评论。

替换评论内容。该评论必须属于路径中指定的仓库、对调用方可见，并且由该调用方创建。跨仓库的评论以及隐藏的待审评论会返回 404；归属于其他主体的可见评论会返回 403。超过 65,536 字符的评论内容会以 InvalidArgument (HTTP 400) 被拒绝。

路径参数

ownerSlug 字符串 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

commentId string 必填

请求体

body string 必填

用于替换的评论内容。最大长度：65,536 个字符，按 Unicode 码点计数。

响应字段

id string

稳定的拉取请求评论标识符。

thread object

该评论所属的线程，包括其 diff 锚点和解决状态。

thread.id string

线程的稳定标识。通过此值将评论归为同一讨论。

thread.version object

该线程所针对的拉取请求版本，包括其 head 与 base 的 SHA。锚点固定在此版本，不会随着拉取请求新增版本而移动。

thread.version.number string

编码为 JSON 字符串的单调拉取请求版本号。

thread.version.headSha string

此拉取请求版本记录的 Head SHA。

thread.version.baseSha string

此拉取请求版本记录的基础 SHA。

thread.version.createdAt string

此拉取请求版本创建时间的 RFC 3339 时间戳。

thread.path string

线程的 diff 锚点所在文件路径。常规讨论线程为空。

thread.side string

锚点所在的 diff 一侧。允许的值：left、right。常规讨论线程不设置此字段。

thread.startLine 整数

文件 side 版本中锚定范围的起始行。文件级别和常规讨论线程使用 0。

thread.endLine 整数

锚定范围的最后一行 (包含) 。当锚点为单行或没有行范围时为 0。

thread.resolvedAt string

线程解决时间的 RFC 3339 时间戳。线程打开时未设置。

thread.createdAt string

RFC 3339 线程创建时间戳。

thread.updatedAt string

线程最近一次更新时间的 RFC 3339 时间戳。

body string

评论内容。

author object

撰写该评论的公开主体。

author.user object

操作主体的用户变体。用户执行该操作时设置。

author.user.id string

用户的公开标识符。

author.user.email string

用户的电子邮件地址。存在用户变体时，始终设置该字段。

author.user.displayName string

用户显示名称：账户的名字和姓氏以空格相连，与产品中呈现的名称相同。若账户没有名称则省略。

author.user.handle string

用户已认领的个人资料 handle，不含 @ 前缀。仅在该个人资料公开可见时返回；否则省略。

author.app object

操作主体的应用变体。在应用执行该操作时设置。

author.app.id string

应用的公开标识符。

author.app.displayName string

应用已注册的显示名称。当该应用无法解析或为 Cursor 的第一方托管主体时将省略。

author.serviceAccount 对象

操作主体的服务帐户变体。服务帐户执行该操作时设置。

author.serviceAccount.id string

服务账户的公开标识符。

createdAt string

RFC 3339 评论创建时间戳。

updatedAt string

最新评论编辑的 RFC 3339 时间戳。
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": "Should the retry budget be configurable?"}'

响应结构：

{  "id": "cmt_01k2ja2000e0080000000000e5",  "thread": {    "id": "cth_01k2ja2000e0080000000000s6",    "version": {      "number": "3",      "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",      "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",      "createdAt": "2026-08-01T09:30:00Z"    },    "path": "src/telemetry/retry.ts",    "side": "right",    "startLine": 42,    "endLine": 45,    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T14:45:00Z"  },  "body": "Should the retry budget be configurable?",  "author": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  },  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z"}

更新拉取请求线程

PATCH/v1/origin/repos/{ownerSlug}/{repoName}/pulls/threads/{threadId}
Scoperepository:pull_requests:reviews:writeAuthInstallation tokenUser access token

解决或重新打开拉取请求的评论线程，并返回该线程更新后的状态。对已解决的线程再次解决，或对已打开的线程再次打开，均为空操作。

该线程必须属于路径中指定的代码仓库；存储在其他代码仓库中的线程将返回 404。可以使用 Create Pull Request Comment 回复已解决的线程，这不会重新打开该线程。

路径参数

ownerSlug string 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

threadId string 必填

稳定的 Origin 线程 ID。

请求体

resolved boolean 必填

目标解决状态。true 表示将该线程标记为已解决；false 表示重新打开该线程。

响应字段

id string

线程的稳定标识。可按此值将同一讨论中的评论归为一组。

version object

该线程所针对的拉取请求版本，包括其 head 和 base 的 SHA。锚点固定于此版本，不会随着拉取请求新增版本而变动。

version.number string

单调递增的 PR 版本号，编码为 JSON string。

version.headSha string

该 PR 版本所记录的 head SHA。

version.baseSha string

此拉取请求版本捕获的基础 SHA。

version.createdAt string

该 PR 版本创建时间的 RFC 3339 时间戳。

path string

线程 diff 锚点所在的文件路径。常规讨论线程该字段为空。

side string

锚点所在的 diff 侧。可选值：left、right。一般讨论线程不设置此值。

startLine 整数

文件 side 版本中锚定范围的起始行。文件级线程和综合讨论线程为 0。

endLine 整数

锚定范围的末行 (包含该行) 。当锚点为单行或不存在行范围时为 0。

resolvedAt string

线程被标记为已解决的 RFC 3339 时间戳。线程处于打开状态时该值未设置。

createdAt string

线程创建时间戳，采用 RFC 3339 格式。

updatedAt string

线程最近一次更新的 RFC 3339 时间戳。
curl --request PATCH \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/threads/THREAD_ID' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "resolved": true}'

响应结构：

{  "id": "cth_01k2ja2000e0080000000000s6",  "version": {    "number": "3",    "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",    "createdAt": "2026-08-01T09:30:00Z"  },  "path": "src/telemetry/retry.ts",  "side": "right",  "startLine": 42,  "endLine": 45,  "resolvedAt": "2026-08-03T10:00:00Z",  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-03T10:00:00Z"}

列出拉取请求的提交

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/commits
Scoperepository:pull_requests:readAuthInstallation tokenUser access token

列出 PR 中的提交。

以精简的 Commit 对象形式返回该拉取请求的提交 (不含 stats) 。结果默认返回 30 条，最大为 100 条，整体最多可见 250 条提交。页面令牌会固定拉取请求版本、页面大小和提交游标；后续请求中的 pageSize 必须与令牌匹配，若令牌与当前的 head 或 base 不再匹配，则返回 400。

路径参数

ownerSlug 字符串 必填

所有者实体的唯一 slug。

repoName string 必填

在所属实体内唯一的仓库名称。

pullNumber string 必填

查询参数

pageSize 整数

要返回的最大提交数。未设置或为 0 时默认为 30。超过 100 的值将被限制为 100。

pageToken string

来自上一次响应中 next_page_token 的不透明游标。首页请求时留空。该 token 与代码仓库、拉取请求版本、每页数量和提交偏移量绑定。

响应字段

提交 数组

精简版提交信息，不含统计数据，总计最多显示 250 条提交。

commits[].sha string

完整的提交 SHA。

commits[].commit 对象

与顶层代码仓库关系分开嵌套的 Git 对象元数据。

commits[].commit.author 对象

提交中记录的 Git 作者身份，而非 Origin 用户对象。

commits[].commit.author.name string

在 Git 作者身份中记录的姓名。

commits[].commit.author.email string

Git 作者身份中记录的电子邮件。

commits[].commit.author.date string

记录在 Git 作者身份中的 RFC 3339 日期。

commits[].commit.committer 对象

记录在该 Git 提交中的提交者身份，而非 Origin 的用户对象。

commits[].commit.committer.name string

Git 身份信息中记录的名称。

commits[].commit.committer.email 字符串

Git 身份中记录的电子邮件地址。

commits[].commit.committer.date string

ISO-8601 时间戳，保留 git signature 的原始时区偏移 (例如 "2014-11-07T22:01:45+01:00") 。

commits[].commit.message string

提交信息。

commits[].commit.tree 对象

该 commit 引用的 tree。

commits[].commit.tree.sha string

提交所引用的树对象的 SHA。

commits[].parents 数组

父提交引用，每项均包含一个 SHA。

commits[].parents[].sha string

父提交的 SHA。

nextPageToken string

Token 会固定拉取请求的版本、页面大小和提交游标；针对当前 head 或 base 过期的 token 会返回 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'

响应结构：

{  "commits": [    {      "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",      "commit": {        "author": {          "name": "Jane Doe",          "email": "jane@acme.dev",          "date": "2026-08-01T09:30:00Z"        },        "committer": {          "name": "Jane Doe",          "email": "jane@acme.dev",          "date": "2026-08-01T09:30:00Z"        },        "message": "Add launch telemetry",        "tree": {          "sha": "a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8"        }      },      "parents": [        {          "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"        }      ],      "stats": {        "additions": 128,        "deletions": 46,        "total": 174      }    }  ]}

列出拉取请求文件

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/files
Scoperepository:pull_requests:readAuthInstallation tokenUser access token

列出 PR 中已更改的文件。

返回文件名、状态、行数统计、补丁以及可选的原文件名。结果默认返回 30 个文件，最多 100 个。页面令牌会固定拉取请求的版本、每页大小和文件游标；后续请求中的 pageSize 必须与该令牌一致，若令牌与当前的 head 或 base 不再匹配，则返回 400。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

pullNumber string 必填

查询参数

pageSize 整数

返回的修改文件数量上限。未设置或设为 0 时，默认值为 30。超过 100 的值将限制为 100。

pageToken string

来自上一个响应的 next_page_token 的不透明游标。第一页为空。该 token 与代码仓库、拉取请求版本、每页数量和变更文件游标绑定。

响应字段

files 数组

当前 PR 版本的文件变更记录。

files[].filename string

PR 中已更改文件的路径。

files[].status string

变更状态；已添加、删除、修改、重命名或复制。

files[].additions 整数

该文件新增的行数。

files[].deletions 整数

文件中已删除的行数。

files[].changes 整数

文件变更的总行数。

files[].patch string

该文件的统一差异补丁。

files[].previousFilename string

文件重命名或复制前的原路径。

nextPageToken string

token 用于固定拉取请求版本、每页数量和文件游标；若 token 相对于当前 head 或 base 过期，则返回 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'

响应结构：

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

列出 PR 标签

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/labels
Scoperepository:pull_requests:readAuthInstallation tokenUser access token

列出分配给 PR 的所有标签，按名称排序。

响应包含完整的已分配标签列表，而非分页结果，因此此端点不接受分页参数。一个 PR 最多可有 100 个标签。找不到的 PR 返回 404。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属所有者实体中唯一。

pullNumber string 必填

响应字段

labels array

当前分配给 PR 的所有标签，按名称排序。

labels[].id string

标签的公开标识符。

labels[].name string

标签名称，在代码仓库内唯一。写入端点使用名称引用标签。

labels[].color string

不含前导 # 的六位十六进制颜色。

labels[].description string

标签没有描述时不返回此字段。
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'

响应结构：

{  "labels": [    {      "id": "lbl_01k2ja2000e0080000000000m1",      "name": "bug",      "color": "d73a4a",      "description": "Something isn't working"    }  ]}

设置 PR 标签

PUT/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/labels
Scoperepository:pull_requests:writeAuthInstallation tokenUser access token

将 PR 上的所有标签替换为指定的标签。

空列表会移除所有已分配的标签。标签必须已存在于代码仓库中；标签名称或 PR 不存在时将返回 404。一个 PR 最多可拥有 100 个标签，因此指定超过 100 个标签将返回 FailedPrecondition (HTTP 400) 。响应会列出替换后分配的标签，并按名称排序。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

在所有者实体内唯一的仓库名称。

pullNumber string 必填

请求体

labels array

要分配的标签名称，最多 100 个。空列表会移除所有已分配的标签。重复的名称将被忽略。

响应字段

labels array

替换后分配的标签，按名称排序。每个条目包含 id、name、color 和 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": [    "bug"  ]}'

响应结构：

{  "labels": [    {      "id": "lbl_01k2ja2000e0080000000000m1",      "name": "bug",      "color": "d73a4a",      "description": "Something isn't working"    }  ]}

添加 PR 标签

POST/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/labels
Scoperepository:pull_requests:writeAuthInstallation tokenUser access token

向 PR 添加现有代码仓库标签。

已分配给 PR 的标签会保留。标签必须已存在于代码仓库中；未知的标签名称或 PR 会返回 404。请求必须指定 1 到 100 个标签，且一个 PR 最多可拥有 100 个标签，因此会使标签总数超过此限制的请求将返回 FailedPrecondition (HTTP 400)。响应会列出请求中指定的标签，而非 PR 的完整标签集；请使用列出 PR 标签获取完整标签集。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属所有者实体中唯一。

pullNumber string 必填

请求体

labels array 必填

要添加的标签名称。最多 100 个。重复名称将被忽略。

响应字段

labels array

请求中指定的标签。每个条目包含 id、name、color 和 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": [    "bug"  ]}'

响应结构：

{  "labels": [    {      "id": "lbl_01k2ja2000e0080000000m1",      "name": "bug",      "color": "d73a4a",      "description": "Something isn't working"    }  ]}

移除 PR 的所有标签

DELETE/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/labels
Scoperepository:pull_requests:writeAuthInstallation tokenUser access token

移除 PR 中的所有标签。

PR 不含任何标签时，请求成功。未找到的 PR 返回 404。响应体为空。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

pullNumber string 必填

响应字段

请求成功时不返回响应体。

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'

响应：

204 No Content

移除 PR 标签

DELETE/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/labels/{labelName}
Scoperepository:pull_requests:writeAuthInstallation tokenUser access token

从 PR 中移除一个标签。

如果标签未分配给该 PR，或 PR 不存在，均会返回 404。响应会列出 PR 上剩余的标签，并按名称排序。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

pullNumber string 必填

labelName string 必填

要移除的标签名称。

响应字段

labels array

PR 上剩余的标签，按名称排序。每个条目包含 id、name、color 和 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'

响应结构：

{  "labels": [    {      "id": "lbl_01k2ja2000e0080000000000m1",      "name": "bug",      "color": "d73a4a",      "description": "Something isn't working"    }  ]}

合并拉取请求

POST/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/merge
Scoperepository:contents:writeAuthInstallation tokenUser access token

将拉取请求合并到其基础分支。

对于堆叠的拉取请求，合并以该拉取请求编号结尾的从根到目标的整个前缀，而不仅仅是该单个拉取请求。仅支持原生 Origin 仓库；镜像仓库将被拒绝。

路径参数

ownerSlug string 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体中唯一。

pullNumber string 必填

要合并的 pull 编号。若该 pull 位于堆栈中，此次合并会将从堆栈根到该编号的所有 pull 一并合并。

请求体

expectedHeadSha string

防止合并您的应用尚未见过的 head：预期为该拉取请求当前 head 的完整提交 SHA (40 或 64 个十六进制字符) 。如果 head 已变动，合并会被拒绝并返回 ABORTED (HTTP 409 Conflict) ，且不会合并任何内容。不是完整提交 SHA 的值会被拒绝并返回 InvalidArgument (HTTP 400) 。省略则合并当前的 head。若拉取请求已合并，则不进行评估并返回幂等成功。

mergeMethod string

拉取请求的合并方式。允许的值：merge，会创建合并提交；squash，会创建单个 squash 提交。仓库不允许的方式会被拒绝并返回 FailedPrecondition (HTTP 400)，其他无效值返回 InvalidArgument (HTTP 400)。省略则使用仓库默认：如果仓库允许则为合并提交，否则为 squash；如果目标分支要求线性历史，则为 squash。

响应字段

mergeCommitSha string

写入 base 的合并提交的 SHA。

mergedPullNumbers 数组

以 JSON 字符串表示的已合并拉取请求编号，从堆栈根到目标。

pullRequest 对象

合并后的目标 PullRequest；尽管示例被简化，但声明的响应类型仍为完整资源。

pullRequest.id string

Stable Origin 拉取请求标识符。

pullRequest.number string

代码仓库内的拉取请求编号，以 JSON 字符串形式编码。

pullRequest.state string

PR 状态：open 或 closed。已合并的 PR 为 closed，且 merged 为 true。

pullRequest.draft boolean

PR 是否为草稿。

pullRequest.merged boolean

该 PR 是否已合并。

pullRequest.title string

PR 标题。

pullRequest.body string

PR 描述正文。

pullRequest.head 对象

该变更的源端——即将被合并的内容所在一侧。

pullRequest.head.ref string

该侧引用所指向的对象 (按 Origin 的记录) 。

pullRequest.head.sha string

该侧在此变更最新版本的顶端提交 SHA。

pullRequest.base 对象

该变更的目标端——即合并入的分支。

pullRequest.base.ref string

该侧引用所指向的对象 (按 Origin 的记录) 。

pullRequest.base.sha string

该侧在此变更最新版本中的顶端提交 SHA。

pullRequest.author 对象

创建该 PR 的公开 actor。

pullRequest.author.user 对象

执行该操作的用户变体。用户执行此操作时设置。

pullRequest.author.user.id string

用户的公开标识符。

pullRequest.author.user.email string

用户的电子邮件地址。存在用户变体时始终设置。

pullRequest.author.user.displayName string

用户显示名称：账户的名字与姓氏以空格连接，即产品显示的名称。账户没有名称时省略。

pullRequest.author.user.handle string

用户认领的个人资料用户名，不含 @ 前缀。仅在该个人资料公开可见时提供；否则省略。

pullRequest.author.app 对象

操作执行者的应用变体。在应用执行该操作时设置。

pullRequest.author.app.id string

应用的公共标识符。

pullRequest.author.app.displayName string

应用的注册显示名称。当应用无法解析或在 Cursor 的第一方托管 actor 上时省略此字段。

pullRequest.author.serviceAccount 对象

actor 的服务账户变体。当服务账户执行该操作时设置。

pullRequest.author.serviceAccount.id string

服务账户的公开标识符。

pullRequest.createdAt string

RFC 3339 格式的 PR 创建时间戳。

pullRequest.updatedAt string

最新拉取请求更新的 RFC 3339 时间戳。

pullRequest.closedAt string

RFC 3339 格式的关闭时间戳；可能出现在已关闭或已合并的拉取请求中。

pullRequest.mergedAt string

RFC 3339 合并时间戳；可能显示在已合并的拉取请求中。

pullRequest.mergeCommitSha string

合并提交的 SHA；可能在合并之后出现。

pullRequest.additions 整数

当前 PR 版本中新增的行。

pullRequest.deletions 整数

当前 PR 版本中被删除的行。

pullRequest.changedFiles 整数

当前拉取请求版本中更改的文件数。

pullRequest.labels 数组

当前分配给拉取请求的标签，按名称排序。若未分配则为空。

pullRequest.labels[].id string

标签的公开标识符。

pullRequest.labels[].name string

标签名称，在仓库内唯一。写入端点使用名称来引用该标签。

pullRequest.labels[].color string

六位十六进制颜色值，不含前导 #。

pullRequest.labels[].description string

标签描述。标签没有描述时不返回此字段。

pullRequest.version 对象

当前编号对应的 PR 版本及其 head/base SHA。

pullRequest.version.number string

编码为 JSON 字符串的单调递增 PR 版本号。

pullRequest.version.headSha string

该拉取请求版本记录的 Head SHA。

pullRequest.version.baseSha string

此拉取请求版本捕获的基础 SHA。

pullRequest.version.createdAt string

该拉取请求版本创建时间的 RFC 3339 时间戳。
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": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",  "mergeMethod": "squash"}'

响应结构：

{  "mergeCommitSha": "5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d",  "mergedPullNumbers": [    "17"  ],  "pullRequest": {    "id": "pr_01k2ja2000e0080000000000d4",    "number": "17",    "state": "closed",    "draft": false,    "merged": true,    "title": "Add launch telemetry",    "body": "Adds structured launch telemetry to the ignition path.",    "head": {      "ref": "add-telemetry",      "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4"    },    "base": {      "ref": "main",      "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"    },    "author": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "jane@acme.dev"      }    },    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T14:45:00Z",    "closedAt": "2026-08-03T10:15:00Z",    "mergedAt": "2026-08-03T10:15:00Z",    "mergeCommitSha": "5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d",    "additions": 128,    "deletions": 46,    "changedFiles": 5,    "labels": [      {        "id": "lbl_01k2ja2000e0080000000000m1",        "name": "bug",        "color": "d73a4a",        "description": "Something isn't working"      }    ],    "version": {      "number": "3",      "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",      "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",      "createdAt": "2026-08-01T09:30:00Z"    }  }}

获取 PR 的可合并性

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/mergeability
Scoperepository:pull_requests:readAuthInstallation tokenUser access token
PreviewThis endpoint is in preview and may change before it is generally available.

返回该拉取请求 (PR) 是否可以合并；如果不能，则列出阻止合并的条件。该判定基于 Merge Pull Request 强制的相同条件，因此 mergeable 判定表示针对相同分支头发起的合并预计会成功。对于堆叠式拉取请求，判定涵盖从堆栈根到当前请求的所有拉取请求，每个阻塞项都会注明其所属的拉取请求。

总计超过 200 个拉取请求的栈 (包括已合并的祖先) 会返回 FailedPrecondition (HTTP 400) 。

此操作处于预览版，在合约定型之前，其结构可能会发生变化。解析响应时请容忍未知字段和未知枚举值；将无法识别的 verdict 视为 blocked；当无法识别 blockers[].kind 时，请渲染 blockers[].message。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体范围内唯一。

pullNumber string 必填

代码仓库内的 PR 编号。

查询参数

expectedHeadSha string

可选保护：完整的提交 SHA (40 或 64 个十六进制字符) ，预期为该拉取请求的当前 head。若设置了该值且被评估的 head 与之不同，请求将返回 Aborted (HTTP 409 Conflict) 而不是结果。若值不是完整的提交 SHA，则返回 InvalidArgument (HTTP 400) 。

响应字段

pullRequest 对象

该决定所针对的 PR。

pullRequest.id string

稳定的 PR 标识符。

pullRequest.number string

仓库内的拉取请求编号，已编码为 JSON 字符串。

pullRequest.repository 对象

拉取请求的代码仓库容器引用。

pullRequest.repository.id string

容器引用中的代码仓库标识符。

pullRequest.repository.name string

container 引用中的代码仓库名称。

pullRequest.repository.owner 对象

代码仓库的所有者引用。

pullRequest.repository.owner.slug string

与所有者 ID 配合使用、用于识别代码仓库所有者的 URL 可见所有者别名 (slug)。

pullRequest.repository.owner.id string

源站所有者标识符。

pullRequest.repository.owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

verdict string

针对 evaluatedPullRequests 中每个 PR 的总体结论。允许的取值：mergeable，表示合并 pullRequest 即可将它们全部合入；以及 blocked。遇到无法识别的取值，按 blocked 处理。

blockers 数组

所有阻止合并的因素，按所属的拉取请求排序，先是分支栈根，然后按类型排序。当 verdict 为 mergeable 时为空。每个拉取请求每种类型最多一个阻塞项，但 required_checks 按每个状态各有一个，rule_failure 和 ruleset_error 则按每个不同消息各有一个。

blockers[].pullRequest 对象

此阻塞项所属的 evaluatedPullRequests 中的拉取请求。包含与 pullRequest 相同的字段。

blockers[].kind string

阻塞项的类别。允许的值：draft、closed、merged、merge_conflict、required_checks、required_approvals、codeowner_approval、behind_base、needs_restack、restack_pending、conflict_check_pending、invalid_stack、ruleset_error、rule_failure。类别会随着时间增加；如果某个阻塞项的类别在您的客户端版本之后才被引入，则解码时其 kind 会保持未设置，但仍然会造成阻塞。

blockers[].message string

以人类可读的形式说明阻塞因素及其清除方法。该字段永不为空，因此无法识别 kind 时应渲染此内容。

blockers[].requiredChecks 对象

设置在 required_checks 阻止器上。

blockers[].requiredChecks.state string

该阻塞因素中所有检查共用的状态。可选值：missing、pending、failing、action_required。

blockers[].requiredChecks.checks 数组

处于该状态的必需检查。

blockers[].requiredChecks.checks[].name string

代码仓库规则要求的名称。

blockers[].requiredChecks.checks[].owner 对象

预期上报该 check 的 principal，其 actor 变体与 check run 的 actor 相同。

blockers[].requiredChecks.checks[].checkRun 对象

以引用形式提供 headSha 上满足此要求的检查运行。若尚未报告任何检查运行，则会省略，状态为 missing。它仅包含 id、name 和 checkSuite.id，因为只需 repository:pull_requests:read 即可读取此操作；而运行的状态、结论、输出和详情 URL 则需要 repository:checks:read，请通过 Get Check Run 读取这些信息。

blockers[].requiredApprovals 对象

在 required_approvals 阻塞因素上设置。

blockers[].requiredApprovals.requiredCount integer

仓库规则所要求的批准评审。

blockers[].requiredApprovals.approvedCount 整数

当前计入要求的批准评审数。

blockers[].codeownerApproval 对象

设置为 codeowner_approval 阻塞。

blockers[].codeownerApproval.requirements 数组

仍需批准的所有者集合。

blockers[].codeownerApproval.requirements[].owners 数组

代码所有者，其中任意一人即可满足该要求。

blockers[].codeownerApproval.requirements[].paths 数组

此所有者集合所覆盖的已更改路径。

blockers[].mergeConflict 对象

在 merge_conflict 阻塞因素上设置。

blockers[].mergeConflict.conflictedPaths 数组

与基础分支冲突的路径，最多列出 100 条。

blockers[].mergeConflict.truncated 布尔值

是否存在未列出的其他冲突路径。

blockers[].mergeConflict.inheritedFromDownstack 布尔值

冲突是否来自分支栈中位于当前 PR 下方的某个 PR，即当前 PR 只是在等待那个 PR，本身并不存在冲突。

blockers[].stackShape 对象

在 invalid_stack 阻塞因素上设置。

blockers[].stackShape.reason string

为什么无法评估此堆栈。允许的值：partially_merged、cycle、missing_parent、cross_repository_parent、base_branch_missing。

blockers[].stackShape.relatedPullRequests 数组

当 reason 中提及时，此处列出涉及的其他 PR。每项的字段与 pullRequest 相同。

evaluatedPullRequests 数组

合入 pullRequest 时将合入的 PR，按分支栈根节点在前、pullRequest 在后的顺序排列。已合并的祖先 PR 属于历史记录，不会列出。未加入分支栈的 PR 仅包含一个元素。每个元素均包含与 pullRequest 相同的字段。

headSha string

已评估的 pullRequest 的 head commit。

baseRef string

评测中的 PR 要合并到的分支：分支栈根分支的基准分支；如果该 PR 是堆叠 PR，则不使用其自身的基准分支。

baseSha string

evaluatedAt 时 baseRef 指向的顶端提交。之后推送到 baseRef 可能会改变判定。如果无法确定基础分支 (例如在分支栈无效时) ，则该值为空。

evaluatedAt string

记录此结果评估时刻的 RFC 3339 时间戳。此时间之后的更改不会反映在结果中；请重新查询以获取。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/mergeability' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'
{  "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": "已批准的评审数为 0；需要 1 个。请请求评审并等待获得所需的批准。",      "requiredApprovals": {        "requiredCount": 1,        "approvedCount": 0      }    },    {      "pullRequest": {        "id": "pr_01k2ja2000e0080000000000d4",        "number": "17",        "repository": {          "id": "repo_01k2ja2000e0080000000000a1",          "name": "launch-control",          "owner": {            "slug": "acme",            "id": "ns_01k2ja2000e0080000000000b2"          }        }      },      "kind": "required_checks",      "message": "必需的状态检查正在等待中。请等待检查完成，或修复未通过的检查。",      "requiredChecks": {        "state": "pending",        "checks": [          {            "name": "ci / build",            "owner": {              "app": {                "id": "app_01k2ja2000e0080000000000e5",                "displayName": "Launch CI"              }            },            "checkRun": {              "id": "cr_01k2ja2000e0080000000000f6",              "name": "ci / build",              "checkSuite": {                "id": "crg_01k2ja2000e0080000000000f7"              }            }          }        ]      }    }  ],  "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"}

列出 PR 请求的审阅人

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/requested_reviewers
Scoperepository:pull_requests:reviews:readAuthInstallation tokenUser access token

列出当前被请求对某个 PR 进行评审的用户和群组。

当某个用户提交评审后，针对该用户的直接请求会被清除；当群组中的任一当前成员提交评审后，针对该群组的请求会被清除。未提交的草稿评审会使请求保持待处理状态；在提交评审后再次请求评审，该审阅人会重新出现在此列表中。没有可读公开标识符的群组将被省略。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

pullNumber string 必填

代码仓库内的 PR 编号。

响应字段

users array

被请求评审的用户。没有待处理请求时为空。

users[].id string

编码后的用户标识符 (user_…) ，与组织 API 使用的格式相同。

users[].email string

用户的电子邮件地址。账户没有电子邮件时为空。

users[].displayName string

用户的显示名称：由账户的名字和姓氏以空格连接而成，与产品中显示的名称相同。账户没有名称时将被省略。

users[].handle string

用户已认领的配置文件 handle，不含 @ 前缀。仅当该配置文件公开可见时存在；否则将被省略。

groups array

被请求评审的群组。没有待处理请求时为空。

groups[].id string

群组的公开标识符 (grp_…) 。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/requested_reviewers' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "users": [    {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  ],  "groups": [    {      "id": "grp_01k2ja2000e0080000000000n2"    }  ]}

请求拉取请求审阅者

POST/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/requested_reviewers
Scoperepository:pull_requests:reviews:writeAuthInstallation tokenUser access token

请求指定用户和群组对某个 PR 进行评审，并返回本次调用所请求的审阅人。

标识符会按仓库的审阅者候选项通过 public id、用户电子邮件或群组 slug 进行解析。显示名称不参与解析。未知或歧义的标识符会返回 InvalidArgument (HTTP 400) 并指明该标识符；在 users 和 groups 中至少要有一个非空条目。

对已请求过的审阅人再次发起请求会刷新请求时间戳，因此已提交评审的审阅人会重新变为待处理状态。若某审阅人不属于该仓库的候选人，则返回 PermissionDenied (HTTP 403)。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体内唯一。

pullNumber string 必填

代码仓库内的 PR 编号。

请求体

users array

要请求的用户标识符。每个条目必须通过公开的 user_… ID 或电子邮件在该仓库中唯一匹配一个用户候选项。

groups array

要请求的组标识符。每个条目必须通过 public grp_... id、限定组 slug 或组 slug 唯一匹配此仓库的组候选项。

响应字段

users array

本次调用请求的用户。

users[].id string

编码后的用户标识符 (user_…) ，与组织 API 使用的格式相同。

users[].email string

用户的电子邮件地址。帐户没有时为空。

users[].displayName string

用户的显示名称：账户的名和姓以空格连接，即产品所展示的名称。若账户没有名称则省略。

users[].handle string

用户已认领的个人资料用户名，不含 @ 前缀。仅在该个人资料公开可见时提供；否则省略。

groups array

此调用请求的群组。

groups[].id string

群组的公有标识符 (grp_…) 。
curl --request POST \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/requested_reviewers' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "users": [    "user_01k2ja2000e0080000000000c3"  ],  "groups": [    "grp_01k2ja2000e0080000000000n2"  ]}'

响应结构：

{  "users": [    {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  ],  "groups": [    {      "id": "grp_01k2ja2000e0080000000000n2"    }  ]}

移除 PR 请求的审阅人

DELETE/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/requested_reviewers
Scoperepository:pull_requests:reviews:writeAuthInstallation tokenUser access token

移除某个 PR 上对指定用户和群组的评审请求。响应体为空。

标识符会按公开 id、用户电子邮件或群组 slug 解析为该代码仓库的审阅候选人。显示名称无法解析。未知或存在歧义的标识符将返回 InvalidArgument (HTTP 400) 并指明该标识符，且 users 与 groups 中至少需要有一个非空条目。

移除当前未被请求的用户或群组不会产生任何效果。若标识符为稳定的公开 id (user_… 或 grp_…) ，即使其已不再是审阅候选人，仍会被接受，因此可以清除已离开该代码仓库的审阅人。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

pullNumber string 必填

代码仓库内的 PR 编号。

请求体

users array

要移除的用户标识符。每个条目必须通过公开 user_… id 或电子邮件唯一匹配该代码仓库的一个用户候选项。

groups array

要移除的群组标识符。每个条目必须通过公开 grp_… id、限定群组 slug 或群组 slug 唯一匹配该代码仓库的一个群组候选项。

响应字段

成功的请求不返回响应体。

curl --request DELETE \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/pulls/PULL_NUMBER/requested_reviewers' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "users": [    "user_01k2ja2000e0080000000000c3"  ],  "groups": [    "grp_01k2ja2000e0080000000000n2"  ]}'

响应：

204 No Content

列出拉取请求评审

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/reviews
Scoperepository:pull_requests:reviews:readAuthInstallation tokenUser access token

列出拉取请求上已提交的评审，按 submitted_at 升序排列。待处理的评审将被省略。

路径参数

ownerSlug string 必填

所有权实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

pullNumber string 必填

查询参数

pageSize 整数

最多返回的评审数。默认值为 30；最大值为 100。

pageToken string

来自上一次响应 nextPageToken 的不透明游标。请求第一页时请省略。

响应字段

reviews 数组

已提交的评审按 submittedAt 升序排列；未提交的草稿评审已被省略。

reviews[].id string

稳定的评审标识符。

reviews[].author 对象

撰写该评论的公开行为者。

reviews[].author.user 对象

执行者的用户变体。用户执行该操作时设置。

reviews[].author.user.id string

用户的公开标识符。

reviews[].author.user.email string

用户的电子邮件地址。存在用户变体时，该字段始终会被设置。

reviews[].author.user.displayName string

用户显示名称：账户的名和姓以空格连接，与产品中显示的名称相同。若账户没有名称则省略。

reviews[].author.user.handle string

用户已认领的个人资料名，不含 @ 前缀。仅在该个人资料公开可见时提供；否则省略。

reviews[].author.app 对象

主体所用应用的变体。由应用执行该操作时设置。

reviews[].author.app.id string

应用的公开标识符。

reviews[].author.app.displayName string

应用已注册的显示名称。当应用无法解析或在 Cursor 的第一方托管主体 (actor) 上时省略。

reviews[].author.serviceAccount 对象

执行者的服务账号变体。当服务账号执行该操作时设置。

reviews[].author.serviceAccount.id string

服务账户的公开标识符。

reviews[].verdict string

评审结论：批准、请求更改或评论。

reviews[].body string

评审摘要文本。

reviews[].submittedAt string

RFC 3339 格式的提交时间戳；未提交的草稿评审不提供此字段。

reviews[].pullRequestVersion 对象

该评审适用的拉取请求版本。

reviews[].pullRequestVersion.number string

单调递增的拉取请求版本号，编码为 JSON 字符串。

reviews[].pullRequestVersion.headSha string

此拉取请求版本捕获的 Head SHA。

reviews[].pullRequestVersion.baseSha string

此拉取请求版本捕获的基准 SHA。

reviews[].pullRequestVersion.createdAt string

该拉取请求版本创建时间的 RFC 3339 时间戳。

reviews[].dismissal 对象

在评审被驳回后显示；被驳回的评审仍会在列表中可见。

reviews[].dismissal.dismissedBy 对象

在被曝光时撤销该评论的公众行为者。

reviews[].dismissal.dismissedBy.user 对象

执行者的用户变体。在用户执行该操作时设置。

reviews[].dismissal.dismissedBy.user.id string

用户的公开标识符。

reviews[].dismissal.dismissedBy.user.email string

用户的电子邮件地址。存在用户变体时，该字段始终会被设置。

reviews[].dismissal.dismissedBy.user.displayName string

用户显示名称：账户的名与姓以空格连接，与产品中呈现的名称相同。若账户没有名称则省略。

reviews[].dismissal.dismissedBy.user.handle string

用户已认领的个人资料名，不含 @ 前缀。仅在该个人资料公开可见时提供；否则省略。

reviews[].dismissal.dismissedBy.app 对象

主体所用应用的变体。由应用执行该操作时设置。

reviews[].dismissal.dismissedBy.app.id string

应用的公开标识符。

reviews[].dismissal.dismissedBy.app.displayName string

应用已注册的显示名称。当应用无法解析或在 Cursor 的第一方托管 actor 上时省略。

reviews[].dismissal.dismissedBy.serviceAccount 对象

执行者的服务账号变体。当服务账号执行该操作时设置。

reviews[].dismissal.dismissedBy.serviceAccount.id string

服务账户的公开标识符。

reviews[].dismissal.dismissedAt string

RFC 3339 格式的撤销时间戳。

reviews[].dismissal.message string

解除原因；自动取代时使用服务器生成的消息。

pullRequest 对象

与评审页面一同提供的 PullRequestReference 容器。

pullRequest.id string

稳定的拉取请求标识符。

pullRequest.number string

代码仓库内的拉取请求编号，以 JSON 字符串形式编码。

pullRequest.repository 对象

该拉取请求的仓库容器引用。

pullRequest.repository.id string

容器引用中的存储库标识符。

pullRequest.repository.name string

容器引用中的存储库名称。

pullRequest.repository.owner 对象

代码仓库的所有者引用。

pullRequest.repository.owner.slug string

面向 URL 的所有者 slug，与所有者 ID 配合使用以标识代码仓库的所有者。

pullRequest.repository.owner.id string

Origin 所有者标识符。

pullRequest.repository.owner.type string

所有者命名空间类型。仅输出。允许的值：team、user。未知时省略。

nextPageToken string

下一页的不透明游标；当没有更多评论时为空。
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'

响应结构：

{  "reviews": [    {      "id": "rev_01k2ja2000e0080000000000f6",      "author": {        "user": {          "id": "user_01k2ja2000e0080000000000c3",          "email": "jane@acme.dev"        }      },      "verdict": "approve",      "body": "Approving. The telemetry schema matches the spec.",      "submittedAt": "2026-08-02T15:00:00Z",      "pullRequestVersion": {        "number": "3",        "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",        "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",        "createdAt": "2026-08-01T09:30:00Z"      }    }  ],  "pullRequest": {    "id": "pr_01k2ja2000e0080000000000d4",    "number": "17",    "repository": {      "id": "repo_01k2ja2000e0080000000000q4",      "name": "rocket",      "owner": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      }    }  }}

创建拉取请求审查

POST/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/reviews
Scoperepository:pull_requests:reviews:writeAuthInstallation tokenUser access token

创建并提交对拉取请求的审查，可选择在同一原子请求中一并提交其评论。每条评论与创建拉取请求评论使用相同的目标：comments[].inline 指定行范围，comments[].file 指定整个文件，comments[].threadId 用于回复，若均不指定则为一般讨论。

评审会立即提交。新的 approve 或 request_changes 评审将取代调用者在同一拉取请求上先前的已生效决策评审，后者将被撤销。拉取请求的作者不能对自己的拉取请求执行 approve。当调用者在该拉取请求上有未提交的草稿评审时，会返回 FAILED_PRECONDITION 错误。

当设置 comments 时，在写入任何内容之前，会针对已审核版本的 diff 验证每个锚点，使用与 Create Pull Request Comment 相同的 diff 内检查。若任一评论验证失败，整个请求将以 InvalidArgument (HTTP 400) 失败，且不会发布任何内容。评论会与审阅原子性地一起可见：在审阅提交之前，任何评论或事件都不可见；提交后，每条评论会与审阅的事件一道触发各自的 pull_request.comment.created webhook。

该操作不包含幂等键，因此在发生不明确的传输故障后重试可能会创建第二个评审。在重试之前请调用列出拉取请求评审。

路径参数

ownerSlug string 必填

所属实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

pullNumber string 必填

请求体

verdict string 必填

评审决定。允许的值：PULL_REQUEST_REVIEW_VERDICT_UNSPECIFIED、approve、request_changes、comment。

body string

自由文本评审摘要。可留空。

versionNumber string

此评审适用的拉取请求版本号 (参见 PullRequestVersion.number) 。省略则在调用时评审最新版本。评论将锚定到相同版本。

comments 数组

随审查一起原子性发布的评论。每次请求最多 50 条。

comments[].body string 必填

评论内容。必须包含至少一个非空白字符。

comments[].inline 对象

评审版本的 diff 中新建内联线程的 diff 锚点。其结构和验证方式与创建拉取请求评论中的 inline 相同。不能与 comments[].threadId 一起使用。

comments[].inline.path string 必填

所审核版本的 diff 中的文件路径。

comments[].inline.side string 必填

锚点所在的差异侧。允许的值：left 表示文件的基础版本，right 表示 head 版本。

comments[].inline.startLine 整数 必填

文件 side 版本中锚定范围的起始行 (行号从 1 开始) 。该范围不得超出该文件的末尾。

comments[].inline.endLine 整数

锚定范围包含的最后一行。必须大于或等于 startLine。对于单行锚点可省略。

comments[].threadId string

要回复的此拉取请求中现有线程的 ID。回复会一直隐藏，直到评审发布。省略 comments[].inline、comments[].file 和此字段以新建一个常规讨论线程。

comments[].file 对象

所评审版本的差异 (diff) 中针对整个文件的新文件级线程的锚点。其结构、侧别推导和验证与创建拉取请求评论中的 file 相同。不能与 comments[].inline 或 comments[].threadId 一起使用。

comments[].file.path string 必填

所审核版本的 diff 中的文件路径：若为删除则为已删除的路径，否则为 head 路径。

响应字段

id string

稳定的评审标识符。

author 对象

创建该评审的公开主体。

author.user 对象

操作主体的用户变体。在用户执行该操作时设置。

author.user.id string

用户的公开标识符。

author.user.email string

用户的电子邮件地址。存在 user 变体时始终设置。

author.user.displayName string

用户的显示名称：账户的名字和姓氏以空格连接，即产品呈现的名称。账户没有名称时省略。

author.user.handle string

用户已认领的个人资料句柄，不含 @ 前缀。仅在该资料公开可见时存在；否则省略。

author.app 对象

操作主体的应用变体。在应用执行该操作时设置。

author.app.id string

应用的公开标识符。

author.app.displayName string

应用的已注册显示名称。在无法解析该应用或在 Cursor 的第一方托管 actor 上时省略。

author.serviceAccount 对象

actor 的服务账户变体。当操作由服务账户执行时，会设置此字段。

author.serviceAccount.id string

服务账户的公开标识符。

verdict string

评审结论：批准、请求更改或评论。

body string

评论摘要文本。

submittedAt string

RFC 3339 提交时间戳；未提交的草稿评审将不包含此字段。

pullRequestVersion 对象

此评审适用的拉取请求版本。

pullRequestVersion.number string

编码为 JSON 字符串的单调递增拉取请求版本号。

pullRequestVersion.headSha string

此 PR 版本记录的 Head SHA。

pullRequestVersion.baseSha string

此 PR 版本记录的基础 SHA。

pullRequestVersion.createdAt string

此拉取请求版本创建时的 RFC 3339 时间戳。

dismissal 对象

撤销评审后依然显示；已撤销的评审仍会在列表中可见。

dismissal.dismissedBy 对象

公开揭露后撤销该评审的主体。

dismissal.dismissedBy.user 对象

操作主体的用户变体。在用户执行该操作时设置。

dismissal.dismissedBy.user.id string

用户的公开标识符。

dismissal.dismissedBy.user.email string

用户的电子邮件地址。存在 user 变体时始终设置。

dismissal.dismissedBy.user.displayName string

用户的显示名称：账户的名字和姓氏以空格连接，即产品呈现的名称。账户没有名称时省略。

dismissal.dismissedBy.user.handle string

用户已认领的个人资料句柄，不含 @ 前缀。仅在该资料公开可见时存在；否则省略。

dismissal.dismissedBy.app 对象

操作主体的应用变体。在应用执行该操作时设置。

dismissal.dismissedBy.app.id string

应用的公开标识符。

dismissal.dismissedBy.app.displayName string

应用的已注册显示名称。在无法解析该应用或在 Cursor 的第一方托管 actor 上时省略。

dismissal.dismissedBy.serviceAccount 对象

actor 的服务账户变体。当操作由服务账户执行时，会设置此字段。

dismissal.dismissedBy.serviceAccount.id string

服务账户的公开标识符。

dismissal.dismissedAt string

RFC 3339 撤销时间戳。

dismissal.message string

撤销原因；自动取代使用服务器生成的消息。
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",  "body": "Approving. The telemetry schema matches the spec.",  "versionNumber": "3"}'

响应结构：

{  "id": "rev_01k2ja2000e0080000000000f6",  "author": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  },  "verdict": "approve",  "body": "Approving. The telemetry schema matches the spec.",  "submittedAt": "2026-08-02T15:00:00Z",  "pullRequestVersion": {    "number": "3",    "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",    "createdAt": "2026-08-01T09:30:00Z"  }}

更新拉取请求审查

PATCH/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/reviews/{reviewId}
Scoperepository:pull_requests:reviews:writeAuthInstallation tokenUser access token

更新评审内容。仅评审作者可以更新；其他调用方将收到 PERMISSION_DENIED。不属于指定拉取请求的评审将返回 NOT_FOUND。

未提交的草稿评审同样可以更新；草稿的响应中不含 submitted_at。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

pullNumber string 必填

reviewId string 必填

请求体

body string 必填

用于替换评审摘要的文本；完整替换原有正文。必须包含非空白字符；否则为 INVALID_ARGUMENT。

响应字段

id string

稳定的评审标识符。

author object

撰写该评论的公共行为体。

author.user object

行为主体的用户变体。用户执行该操作时设置。

author.user.id string

用户的公开标识符。

author.user.email string

该用户的电子邮件地址。存在 user 变体时始终会设置该字段。

author.user.displayName string

用户显示名称：账户的名字和姓氏以空格连接，为产品呈现的相同名称。若账户没有名称则省略。

author.user.handle string

用户已认领的个人资料用户名，不含 @ 前缀。仅在该个人资料公开可见时提供；否则省略。

author.app object

行为主体的应用变体。应用执行该操作时设置。

author.app.id string

应用的公开标识符。

author.app.displayName string

应用已注册的显示名称。当应用无法解析或在 Cursor 的第一方托管主体上时将被省略。

author.serviceAccount object

操作主体的服务账户变体。服务账户执行该操作时设置。

author.serviceAccount.id string

服务账户的公共标识符。

verdict string

评审决定：批准、请求更改或评论。

body string

评审摘要文本。

submittedAt string

RFC 3339 提交时间戳；未提交的草稿评审则不含此字段。

pullRequestVersion 对象

该评审所针对的拉取请求版本。

pullRequestVersion.number string

以 JSON 字符串编码的单调递增拉取请求版本号。

pullRequestVersion.headSha string

此拉取请求版本记录的 Head SHA。

pullRequestVersion.baseSha string

此 PR 版本记录的基础 SHA。

pullRequestVersion.createdAt string

该 PR 版本创建时间的 RFC 3339 时间戳。

dismissal 对象

在评审被驳回后仍然存在；被驳回的评审在列表中仍然可见。

dismissal.dismissedBy object

在被曝光后撤回该评价的公众人物。

dismissal.dismissedBy.user 对象

行为主体的用户变体。用户执行该操作时设置。

dismissal.dismissedBy.user.id string

用户的公开标识符。

dismissal.dismissedBy.user.email string

该用户的电子邮件地址。存在 user 变体时始终会设置该字段。

dismissal.dismissedBy.user.displayName string

用户显示名称：账户的名和姓以空格连接，为产品呈现的相同名称。若账户没有名称则省略。

dismissal.dismissedBy.user.handle string

用户已认领的个人资料用户名，不含 @ 前缀。仅在该个人资料公开可见时提供；否则省略。

dismissal.dismissedBy.app 对象

行为主体的应用变体。由应用执行该操作时设置。

dismissal.dismissedBy.app.id string

应用的公开标识符。

dismissal.dismissedBy.app.displayName string

应用已注册的显示名称。当应用无法解析或在 Cursor 的第一方托管主体上时会被省略。

dismissal.dismissedBy.serviceAccount 对象

操作主体的服务账户变体。服务账户执行该操作时设置。

dismissal.dismissedBy.serviceAccount.id string

服务账户的公共标识符。

dismissal.dismissedAt string

RFC 3339 驳回时间戳。

dismissal.message string

解除原因；自动取代时使用服务器生成的消息。
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": "Approving. The telemetry schema matches the spec."}'

响应结构：

{  "id": "rev_01k2ja2000e0080000000000f6",  "author": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  },  "verdict": "approve",  "body": "Approving. The telemetry schema matches the spec.",  "submittedAt": "2026-08-02T15:00:00Z",  "pullRequestVersion": {    "number": "3",    "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",    "createdAt": "2026-08-01T09:30:00Z"  }}

关闭拉取请求评审

PUT/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/reviews/{reviewId}/dismissals
Scoperepository:pull_requests:reviews:writeAuthInstallation tokenUser access token

撤销已提交的评审，使其裁定不再计入拉取请求的评审状态。评审本身会被保留，并继续出现在 ListPullRequestReviews 中，且 dismissal 已设置。

无需由评审作者执行撤销操作；拥有该代码仓库 PR 评审的写入权限即可。

只有 approve 和 request_changes 两种评审可以被撤销，且仅能撤销一次：对 comment 评审、未提交的草稿评审或已被撤销的评审的调用会返回 FAILED_PRECONDITION，重复调用将保留第一次的撤销。不属于指定拉取请求的评审会返回 NOT_FOUND。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体中唯一。

pullNumber string 必填

reviewId string 必填

由 ListPullRequestReviews 返回的稳定 Origin 审查标识符。

请求体

message string 必填

随驳回一并记录的原因。必须包含非空白字符；否则返回 INVALID_ARGUMENT。

响应字段

id string

稳定的评审标识符。

author object

撰写该评论的公共行为者。

author.user object

行为主体的用户变体。用户执行该操作时设置。

author.user.id string

用户的公开标识符。

author.user.email string

用户的电子邮件地址。若存在用户变体，则始终设置。

author.user.displayName string

用户的显示名称：账户的名字和姓氏以空格连接，与产品显示的名称相同。账户没有名称时省略。

author.user.handle string

用户已认领的个人资料用户名，不含 @ 前缀。仅在该个人资料公开可见时提供；否则省略。

author.app object

行为主体的应用变体。仅在应用执行该操作时设置。

author.app.id string

应用的公开标识符。

author.app.displayName string

应用的注册显示名称。当应用无法解析，或为 Cursor 第一方托管的主体时省略。

author.serviceAccount object

操作主体的服务账户变体。由服务账户执行该操作时设置。

author.serviceAccount.id string

服务账户的公共标识符。

verdict string

评审决定：批准 (approve) 、请求更改 (request_changes) 或评论 (comment) 。

body string

评审摘要文本。

submittedAt string

RFC 3339 提交时间戳；对于未提交的草稿评审，该字段缺失。

pullRequestVersion 对象

该评审适用于的拉取请求版本。

pullRequestVersion.number string

单调递增的拉取请求版本号，编码为 JSON 字符串。

pullRequestVersion.headSha string

此拉取请求版本记录的 Head SHA。

pullRequestVersion.baseSha string

该 PR 版本记录的 base SHA。

pullRequestVersion.createdAt string

此拉取请求版本创建时间的 RFC 3339 时间戳。

dismissal 对象

在评审被撤销后显示；已撤销的评审仍在列表中可见。

dismissal.dismissedBy 对象

在被曝光时撤销该评审的公开行为者。

dismissal.dismissedBy.user 对象

行为主体的用户变体。用户执行该操作时设置。

dismissal.dismissedBy.user.id string

用户的公开标识符。

dismissal.dismissedBy.user.email string

用户的电子邮件地址。若存在用户变体，则始终设置。

dismissal.dismissedBy.user.displayName string

用户的显示名称：账户的名字和姓氏以空格连接，与产品呈现的名称相同。账户没有名称时省略。

dismissal.dismissedBy.user.handle string

用户已认领的个人资料用户名，不含 @ 前缀。仅在该个人资料公开可见时提供；否则省略。

dismissal.dismissedBy.app 对象

行为主体的应用变体。在应用执行该操作时设置。

dismissal.dismissedBy.app.id string

应用的公开标识符。

dismissal.dismissedBy.app.displayName string

应用的注册显示名称。当应用无法解析或为 Cursor 的第一方托管主体时省略。

dismissal.dismissedBy.serviceAccount 对象

操作主体的服务账号变体。在服务账号执行该操作时设置。

dismissal.dismissedBy.serviceAccount.id string

服务账户的公开标识符。

dismissal.dismissedAt string

RFC 3339 驳回时间戳。

dismissal.message string

撤销原因；自动替代使用服务器生成的消息。
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": "Superseded by a newer review."}'

响应结构：

{  "id": "rev_01k2ja2000e0080000000000f6",  "author": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  },  "verdict": "approve",  "body": "Approving. The telemetry schema matches the spec.",  "submittedAt": "2026-08-02T15:00:00Z",  "pullRequestVersion": {    "number": "3",    "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",    "createdAt": "2026-08-01T09:30:00Z"  },  "dismissal": {    "dismissedBy": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "jane@acme.dev"      }    },    "dismissedAt": "2026-08-02T15:00:00Z",    "message": "Superseded by a newer review."  }}

规则集

列出规则集

GET/v1/origin/repos/{ownerSlug}/{repoName}/rulesets
Scoperepository:rulesets:readAuthInstallation tokenUser access token

列出代码仓库中配置的所有规则集。

每个代码仓库的规则集数量有限，因此会在单个响应中返回完整集合，此端点不进行分页。repository 仅在响应中出现一次，用于描述所有规则集共享的代码仓库。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体范围内唯一。

响应字段

rulesets 数组

代码仓库中已配置的规则集。

rulesets[].id string

Stable Origin 规则集 ID。

rulesets[].name string

规则集名称。

rulesets[].description string

规则集描述。

rulesets[].enforcement string

Origin 强制执行该规则集的方式。允许的值：active、evaluate、disabled。

rulesets[].kind string

规则集所保护的操作。允许的值：merge_branch、push_branch、push_tag、push_repository。

rulesets[].includedRefNames 数组

此规则集包含的引用名称模式。支持 glob 以及 ~ALL 和 ~DEFAULT_BRANCH 两个标记。

rulesets[].excludedRefNames 数组

此规则集排除的引用名称模式。使用与 rulesets[].includedRefNames 相同的模式语言。

rulesets[].rules 数组

此规则集中包含的保护规则。

rulesets[].rules[].id string

此规则的稳定 Origin ID。

rulesets[].rules[].ruleType string

规则类型，例如 pull_request、require_status_checks、require_branch_up_to_date、deletion 或 non_fast_forward。

rulesets[].rules[].parameters 对象

以 JSON 对象形式指定特定于类型的参数。其结构取决于 rulesets[].rules[].ruleType。

rulesets[].bypassActors 数组

可绕过此规则集的主体。若某个绕过主体的已存储身份无法读取，则会从响应中省略。

rulesets[].bypassActors[].id string

此绕过主体的稳定 Origin ID。

rulesets[].bypassActors[].bypassMode string

绕过何时生效。允许的值：always、pull_request_only。

rulesets[].bypassActors[].user 对象

一个用户主体。user、team、app 或 originRole 中恰有且仅有一个存在。

rulesets[].bypassActors[].user.id string

以十进制字符串编码的数字光标用户 ID。

rulesets[].bypassActors[].team 对象

车队负责人。

rulesets[].bypassActors[].team.organizationPublicId string

不可更改的组织公开 ID。

rulesets[].bypassActors[].team.groupPublicId string

不可变的群组公开 ID。

rulesets[].bypassActors[].app 对象

应用主体。

rulesets[].bypassActors[].app.id string

应用 ID，前缀为 app_。

rulesets[].bypassActors[].originRole 对象

拥有 Origin 角色的主体。

rulesets[].bypassActors[].originRole.role string

允许的值：namespace_admin、repository_admin、repository_write。

repository 对象

此响应中所有规则集共享的代码仓库。

repository.id string

容器引用中的存储库标识符。

repository.name string

容器引用中的仓库名称。

repository.owner 对象

该代码仓库的所有者引用。

repository.owner.slug string

与所有者 ID 配合使用、用于标识代码仓库所有者的 URL 标识符。

repository.owner.id string

Origin 所有者标识符。

repository.owner.type string

所属命名空间的类型。仅输出。允许的值：team、user。未知时省略。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/repos/OWNER_SLUG/REPO_NAME/rulesets' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "rulesets": [    {      "id": "rs_01k2ja2000e0080000000000t7",      "name": "require-review",      "description": "Require an approving review before merging to main.",      "enforcement": "active",      "kind": "merge_branch",      "includedRefNames": [        "refs/heads/main"      ],      "rules": [        {          "id": "rsr_01k2ja2000e0080000000000v8",          "ruleType": "pull_request",          "parameters": {            "requiredApprovingReviewCount": 1          }        }      ],      "bypassActors": [        {          "id": "rsba_01k2ja2000e0080000000000w9",          "bypassMode": "always",          "user": {            "id": "act_01k2ja2000e0080000000000x0"          }        }      ]    }  ],  "repository": {    "id": "repo_01k2ja2000e0080000000000q4",    "name": "rocket",    "owner": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    }  }}

创建规则集

POST/v1/origin/repos/{ownerSlug}/{repoName}/rulesets
Scoperepository:rulesets:writeAuthInstallation tokenUser access token

创建代码仓库规则集。

响应中包含已存储的规则集，其中包括 Origin 为每条规则和绕过主体分配的 ID。空的 name 会被拒绝，并返回 InvalidArgument (HTTP 400) 。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所有者实体范围内唯一。

请求体

name string 必填

规则集名称。

description string

规则集说明。

enforcement string 必填

Origin 强制执行规则集的方式。可选值：active、evaluate、disabled。

kind string 必填

规则集所保护的操作。可选值：merge_branch、push_branch、push_tag、push_repository。

includedRefNames 数组

此规则集包含的引用名称模式。支持 glob 和标记 ~ALL 与 ~DEFAULT_BRANCH。条目数超过 64 将返回 InvalidArgument (HTTP 400) 。

excludedRefNames 数组

此规则集排除的引用名称模式。使用与 includedRefNames 相同的模式语言，最多可包含 64 项。

rules 数组

要存储的保护规则。每个条目包含 ruleType 和可选的 parameters；Origin 会为每条规则分配 id。条目数超过 20 个将被拒绝并返回 InvalidArgument (HTTP 400) 。

bypassActors array

要存储的绕过主体。每个条目包含 bypassMode，以及 user、team、app 或 originRole 中的一个；Origin 为每个主体分配 id。条目数超过 15 个时将被拒绝并返回 InvalidArgument (HTTP 400) 。

响应字段

id string

稳定的 Origin 规则集 ID。

name string

规则集名称。

description string

规则集说明。

enforcement string

Origin 强制执行规则集的方式。可选值：active、evaluate、disabled。

kind string

规则集所保护的操作。允许的值：merge_branch、push_branch、push_tag、push_repository。

includedRefNames 数组

此规则集包含的引用名称模式。支持 glob 通配符，以及标记 ~ALL 和 ~DEFAULT_BRANCH。

excludedRefNames 数组

此规则集排除的引用名称模式。使用与 includedRefNames 相同的模式语法。

rules 数组

此规则集中包含的保护规则。

rules[].id string

此规则的稳定源站 ID。

rules[].ruleType string

规则类型，例如 pull_request、require_status_checks、require_branch_up_to_date、deletion 或 non_fast_forward。

rules[].parameters 对象

以 JSON 对象形式表示的类型特定参数。其结构取决于 rules[].ruleType。

bypassActors array

可绕过此规则集的主体。若无法读取绕过主体存储的身份信息，则该主体不会出现在响应中。

bypassActors[].id string

该绕过 Actor 的稳定原点 ID。

bypassActors[].bypassMode string

绕过规则的生效时机。允许的值：always、pull_request_only。

bypassActors[].user 对象

用户主体。user、team、app 或 originRole 中有且仅有一个存在。

bypassActors[].user.id string

数字游标用户 ID，使用十进制字符串编码。

bypassActors[].team object

车队经理。

bypassActors[].team.organizationPublicId string

不可变的组织公开 ID。

bypassActors[].team.groupPublicId string

不可变的群组公开 ID。

bypassActors[].app 对象

一个应用主体。

bypassActors[].app.id string

应用 ID，以 app_ 为前缀。

bypassActors[].originRole 对象

具有 Origin 角色的主体。

bypassActors[].originRole.role string

允许的值：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": "require-review",  "description": "Require an approving review before merging to main.",  "enforcement": "active",  "kind": "merge_branch",  "includedRefNames": [    "refs/heads/main"  ],  "rules": [    {      "ruleType": "pull_request",      "parameters": {        "requiredApprovingReviewCount": 1      }    }  ],  "bypassActors": [    {      "bypassMode": "always",      "user": {        "id": "act_01k2ja2000e0080000000000x0"      }    }  ]}'

响应结构：

{  "id": "rs_01k2ja2000e0080000000000t7",  "name": "require-review",  "description": "Require an approving review before merging to main.",  "enforcement": "active",  "kind": "merge_branch",  "includedRefNames": [    "refs/heads/main"  ],  "rules": [    {      "id": "rsr_01k2ja2000e0080000000000v8",      "ruleType": "pull_request",      "parameters": {        "requiredApprovingReviewCount": 1      }    }  ],  "bypassActors": [    {      "id": "rsba_01k2ja2000e0080000000000w9",      "bypassMode": "always",      "user": {        "id": "act_01k2ja2000e0080000000000x0"      }    }  ]}

获取规则集

GET/v1/origin/repos/{ownerSlug}/{repoName}/rulesets/{rulesetId}
Scoperepository:rulesets:readAuthInstallation tokenUser access token

根据稳定的 Origin ID 返回单个代码仓库规则集。

未知的代码仓库和未知的规则集都会返回 404，可通过返回的消息加以区分。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

rulesetId string 必填

Stable Origin 规则集 ID。

响应字段

id string

稳定的源规则集 ID。

name string

规则集名称。

description string

规则集描述。

enforcement string

Origin 对规则集的执行方式。可选值：active、evaluate、disabled。

kind string

规则集所保护的操作。允许的值：merge_branch、push_branch、push_tag、push_repository。

includedRefNames 数组

此规则集包含的引用名称模式。支持 glob 模式以及标记 ~ALL 和 ~DEFAULT_BRANCH。

excludedRefNames 数组

此规则集排除的引用名称模式。模式语法与 includedRefNames 相同。

rules 数组

此规则集中的保护规则。

rules[].id string

此规则的稳定源站 ID。

rules[].ruleType string

规则类型，例如 pull_request、require_status_checks、require_branch_up_to_date、deletion 或 non_fast_forward。

rules[].parameters 对象

以 JSON 对象形式的类型特定参数。其结构取决于 rules[].ruleType。

bypassActors array

可绕过此规则集的主体。若无法读取绕过主体所存储的身份信息，则会在响应中将其省略。

bypassActors[].id string

此绕过参与者的稳定原点 ID。

bypassActors[].bypassMode string

绕过规则的生效时机。可选值：always、pull_request_only。

bypassActors[].user 对象

用户主体。user、team、app 或 originRole 中有且仅有一个。

bypassActors[].user.id string

以十进制字符串编码的数字游标用户 ID。

bypassActors[].team 对象

车队领队。

bypassActors[].team.organizationPublicId string

不可变的组织 public ID。

bypassActors[].team.groupPublicId string

不可变的群组公开 ID。

bypassActors[].app 对象

应用主体。

bypassActors[].app.id string

应用 ID，以 app_ 为前缀。

bypassActors[].originRole 对象

拥有 Origin 角色的主体。

bypassActors[].originRole.role string

允许的值：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'

响应结构：

{  "id": "rs_01k2ja2000e0080000000000t7",  "name": "require-review",  "description": "Require an approving review before merging to main.",  "enforcement": "active",  "kind": "merge_branch",  "includedRefNames": [    "refs/heads/main"  ],  "rules": [    {      "id": "rsr_01k2ja2000e0080000000000v8",      "ruleType": "pull_request",      "parameters": {        "requiredApprovingReviewCount": 1      }    }  ],  "bypassActors": [    {      "id": "rsba_01k2ja2000e0080000000000w9",      "bypassMode": "always",      "user": {        "id": "act_01k2ja2000e0080000000000x0"      }    }  ]}

更新规则集

PUT/v1/origin/repos/{ownerSlug}/{repoName}/rulesets/{rulesetId}
Scoperepository:rulesets:writeAuthInstallation tokenUser access token

更新现有的代码仓库规则集。

该请求会替换整个规则集配置。rules 和 bypassActors 会被完全替换，而不会合并；Origin 会为已存储的条目分配新的 ID，因此请发送所有要保留的规则和绕过主体。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属实体内唯一。

rulesetId string 必填

稳定的源规则集 ID。

请求体

name string 必填

规则集名称。

description string

规则集描述。

enforcement string 必填

Origin 执行规则集的方式。可选值：active、evaluate、disabled。

kind string 必填

规则集所保护的操作。允许的值：merge_branch、push_branch、push_tag、push_repository。

includedRefNames 数组

此规则集包含的引用名称模式。支持 glob 与标记 ~ALL 和 ~DEFAULT_BRANCH。超过 64 个条目的值会被拒绝，并返回 InvalidArgument (HTTP 400) 。

excludedRefNames 数组

此规则集排除的引用名称模式。与 includedRefNames 使用相同的模式语法，且同样最多 64 项。

rules 数组

要存储的保护规则。每个条目包含 ruleType 和可选的 parameters；Origin 会为每条规则分配 id。条目数超过 20 个将被拒绝，返回 InvalidArgument (HTTP 400) 。

bypassActors 数组

要存储的绕过主体。每个条目包含 bypassMode，以及 user、team、app 或 originRole 中的恰好一个；Origin 会为每个主体分配 id。超过 15 个条目将被拒绝，返回 InvalidArgument (HTTP 400) 。

响应字段

id string

稳定的源规则集 ID。

name string

规则集名称。

description string

规则集描述。

enforcement string

Origin 执行规则集的方式。可选值：active、evaluate、disabled。

kind string

规则集所保护的操作。允许的值：merge_branch、push_branch、push_tag、push_repository。

includedRefNames 数组

此规则集中包含的引用名称模式。支持 glob 以及标记 ~ALL 和 ~DEFAULT_BRANCH。

excludedRefNames 数组

此规则集要排除的引用名称模式。使用与 includedRefNames 相同的模式语言。

rules 数组

此规则集中的保护规则。

rules[].id string

该规则的稳定 Origin ID。

rules[].ruleType string

规则类型，例如 pull_request、require_status_checks、require_branch_up_to_date、deletion 或 non_fast_forward。

rules[].parameters 对象

特定类型的参数，以 JSON 对象形式提供。其结构取决于 rules[].ruleType。

bypassActors 数组

可绕过此规则集的主体。若绕过主体的已存储身份无法读取，则不会显示在响应中。

bypassActors[].id string

此绕过 actor 的稳定 Origin ID。

bypassActors[].bypassMode string

绕过规则的生效时机。可选值：always、pull_request_only。

bypassActors[].user 对象

用户主体。user、team、app 或 originRole 中仅存在一个。

bypassActors[].user.id string

以十进制字符串编码的数字 Cursor 用户 ID。

bypassActors[].team 对象

车队领队。

bypassActors[].team.organizationPublicId string

不可变的组织公共 ID。

bypassActors[].team.groupPublicId string

不可更改的群组公开 ID。

bypassActors[].app 对象

应用主体。

bypassActors[].app.id string

应用 ID，以 app_ 为前缀。

bypassActors[].originRole 对象

拥有 Origin role 的 principal。

bypassActors[].originRole.role string

允许的值：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": "require-review",  "description": "Require an approving review before merging to main.",  "enforcement": "active",  "kind": "merge_branch",  "includedRefNames": [    "refs/heads/main"  ],  "rules": [    {      "ruleType": "pull_request",      "parameters": {        "requiredApprovingReviewCount": 1      }    }  ],  "bypassActors": [    {      "bypassMode": "always",      "user": {        "id": "act_01k2ja2000e0080000000000x0"      }    }  ]}'

响应结构：

{  "id": "rs_01k2ja2000e0080000000000t7",  "name": "require-review",  "description": "Require an approving review before merging to main.",  "enforcement": "active",  "kind": "merge_branch",  "includedRefNames": [    "refs/heads/main"  ],  "rules": [    {      "id": "rsr_01k2ja2000e0080000000000v8",      "ruleType": "pull_request",      "parameters": {        "requiredApprovingReviewCount": 1      }    }  ],  "bypassActors": [    {      "id": "rsba_01k2ja2000e0080000000000w9",      "bypassMode": "always",      "user": {        "id": "act_01k2ja2000e0080000000000x0"      }    }  ]}

删除规则集

DELETE/v1/origin/repos/{ownerSlug}/{repoName}/rulesets/{rulesetId}
Scoperepository:rulesets:writeAuthInstallation tokenUser access token

根据稳定的 Origin ID 删除代码仓库规则集。响应体为空。

未知代码仓库和未知规则集均返回 404，消息会区分二者。存储在其他代码仓库中的规则集会被视为未知规则集。空 rulesetId 返回 InvalidArgument (HTTP 400)。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

仓库名称，在所属所有者实体中唯一。

rulesetId string 必填

稳定的 Origin 规则集 ID。

响应字段

成功的请求不返回响应体。

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

响应：

204 No Content

Webhooks

Origin 会向应用已注册的 HTTPS webhook URL 发送已签名的 HTTP POST 请求，内容类型为 application/json。

投递至少一次。使用 webhook-id 对重试请求去重，持久化接收请求，快速返回 2xx，并异步处理事件。

对于传输错误、429 和 5xx 响应，Origin 最多重试七次。重试间隔依次为 5 秒、30 秒、1 分钟、2 分钟、4 分钟和 8 分钟。其他 4xx 响应不会重试。

若要在任何真实事件到达接收方之前确认其是否正常工作，请调用 Ping Webhook。

Origin 会为镜像仓库投递事件，安装事件负载会在所选代码仓库数组中列出这些代码仓库。投递不会扩大安装可调用的范围：请参阅 镜像仓库。

请求头

请求头描述
content-typeapplication/json
user-agentCursor-Origin-Webhook/1.0
webhook-id稳定的投递 ID 和幂等键。
webhook-timestamp签名中包含的 Unix 时间戳。
webhook-signaturev1ed,BASE64_SIGNATURE
webhook-event-type用于路由的事件 slug。
webhook-event-id从已签名请求体中镜像的底层 Origin 事件 ID。
webhook-app-id目标应用 ID。
webhook-installation-id目标安装 ID。

路由请求头仅为方便起见。验证签名后，应以请求体为准。

签名验证

请在解析前使用原始请求体。构造：

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

使用有效的 Origin JWKS 密钥，验证该十六进制摘要的 UTF-8 字节所对应的 Ed25519 签名。拒绝与当前时间相差超过五分钟的时间戳。

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");  // 生产环境中请缓存此响应。  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;    }  });}

投递封装

每个请求都会将事件负载连同投递、应用和安装身份信息一并封装：

{  "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 在重试时保持不变。event.id 标识底层域名事件。

恢复

使用 应用 JWT 查询 GET /app/webhook/deliveries。可按投递状态、事件类型、安装、时间范围或页面 token 进行筛选。delivered=false 会返回接收方从未以 2xx 状态码确认的所有投递记录。投递记录可查询七天，因此请在此时间窗口内恢复。

使用 POST /app/webhook/deliveries:batchRedeliver 可将最多 100 个投递 ID 加入重新投递队列。该操作会对 ID 去重，并返回每个投递的结果。

所有者可以在应用设置中暂停应用的 webhook 投递，源站也可以自行暂停：如果某个应用的接收方在 72 小时窗口内至少 20 轮投递均失败，且该窗口内没有任何一次成功投递，同时失败涉及多个安装方命名空间，该应用会被自动禁用。无论哪种情况，投递都会停止，直到所有者恢复它；重新投递请求会返回 FailedPrecondition (HTTP 400) ，不会有任何内容加入队列；并且 API 不会暴露表示暂停状态的字段，因此请将重新投递返回的 FailedPrecondition 视为判断信号。通过 Update App 清除应用的 webhookUrl 影响更大：它会直接取消待处理的投递，即使重新设置 URL 也无法恢复。

Webhooks 参考

这里列出 Origin 投递的所有事件，并逐个字段说明每个事件的负载。有关订阅机制、请求头、签名验证、投递封装和重试，请参见 Webhooks。

事件

事件触发时机
repository.created创建代码仓库时。
repository.deleted删除代码仓库时。
repository.pushed推送导致一个或多个引用发生更改。
repository.metadata.updated代码仓库的默认分支发生更改时。
pull_request.createdPR 创建时。
pull_request.head_ref.pushedPR 的头部引用推进时。
pull_request.base_ref.updatedbase 引用或解析后的基础提交发生更改时。
pull_request.metadata.updated标题或描述发生更改时。
pull_request.closedPR 未合并即关闭时，包括因推送导致其头部与 base 之间没有共同历史而由 Origin 关闭的情况。
pull_request.mergedPR 合并时。
pull_request.reopened已关闭的 PR 重新打开时。
pull_request.published草稿 PR 变为开放状态时。
pull_request.comment.created创建可见的 PR 评论时。
pull_request.review.submitted提交任意决定的评审时。
pull_request.review.dismissed已提交的评审被明确撤销或被后续评审取代时。
pull_request.reviewer.added请求审阅人时。
pull_request.reviewer.removed移除审阅人时。
pull_request.reviewer.rerequested再次请求审阅人时。
repository.check_run.created创建检查运行时。
repository.check_run.completed检查运行完成时。
repository.check_run.rerequested已完成的检查运行被重新请求时。仅投递给拥有该运行的应用。
installation.created安装应用时。
installation.updated权限范围、代码仓库选择或所有者 namespace 的 slug 发生更改时。
installation.suspended安装被暂停时。
installation.unsuspended已暂停的安装恢复时。
installation.deleted卸载应用时。

每个事件的负载结构都在 事件负载 中逐字段说明。

五个 installation.* 事件会发送给应用本身，而非代码仓库订阅。Origin 始终会发送这些事件，因此它们不会出现在应用的可选择事件列表中。本表中的其他所有事件都是代码仓库范围的订阅。

对于从 GitHub 镜像而来的代码仓库，Origin 不会投递 repository.pushed。这些推送归 GitHub 所有，并由其发送自己的推送 Webhook，因此 Origin 再投递一次会造成重复。对原生 Origin 仓库以及出站镜像的推送会照常投递，镜像状态不会影响任何其他事件。对于从 GitHub 镜像而来的代码仓库，repository.deleted 会被投递：停止同步只会删除 Cursor 侧的代码仓库，GitHub 不会为此发送任何事件。

事件负载

每个事件的投递封装会在 payload 字段中携带该事件的负载对象。结构相同的事件属于同一负载系列；下面每个系列均列出了使用该负载的事件、其字段以及一个示例负载，这些内容均由 OpenAPI 规范生成。

代码仓库已创建

EVENTrepository.created

负载字段

repository 对象

所创建的代码仓库。

repository.id string

repository.name string 必填

仓库名称，在其所有者下唯一。创建时必填。

repository.fullName string

"{owner.login}/{name}"。自动派生。

repository.owner 对象

所有者实体。创建时由父级决定，不可直接设置。

repository.owner.slug string

owner 的唯一 URL 友好名称。

repository.owner.id string

所有者 namespace 的唯一 ID。

repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

repository.defaultBranch string

默认分支名称。在响应中始终会设置。创建时若省略该字段或留空，则默认为 "main"。

repository.createdAt string

RFC 3339 格式的 timestamp。

repository.updatedAt string

RFC 3339 格式的 timestamp。

repository.pushedAt string

任意分支上最近一次推送的时间戳；首次推送前不返回该字段。格式为 RFC 3339 时间戳。

repository.cloneUrl string

用于克隆代码仓库的 HTTPS URL。

repository.mirror 对象

镜像元数据。对于 native 代码仓库，以及镜像首次同步就绪之前，该字段不会返回。

repository.mirror.source string

取值之一：github。

repository.mirror.sourceId string

由来源分配的不透明代码仓库标识符。

repository.mirror.status string

过渡期间的生效方向，直至切换完成。取值为 inbound 或 outbound。

repository.visibility string

代码仓库可见性，internal 或 private。取值为 internal、private 之一。

repository.allowMergeCommit boolean

PR 是否可以以 merge 提交的方式合入。

repository.allowSquashMerge boolean

PR 是否可以以 squash merge 方式合入。

repository.deleteBranchOnMerge boolean

merge 时是否自动删除 head 分支。

event.payload 示例：

{  "repository": {    "id": "repo_01k2ja2000e0080000000000q4",    "name": "rocket",    "fullName": "acme/rocket",    "owner": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    },    "defaultBranch": "main",    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-01T09:30:00Z",    "cloneUrl": "https://origin.cursor.com/git/acme/rocket.git"  }}

代码仓库已删除

EVENTrepository.deleted

负载字段

repository object

被删除的代码仓库。仅作引用：删除后该代码仓库无法再通过 API 解析。

repository.id string

repository.name string

repository.owner object

仓库的所有者。

repository.owner.slug string

所有者的唯一名称，适用于 URL。

repository.owner.id string

所有者 namespace 的唯一 ID。

repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

deletedAt string

代码仓库被删除的时间。RFC 3339 时间戳。

event.payload 示例：

{  "repository": {    "id": "repo_01k2ja2000e0080000000000q4",    "name": "rocket",    "owner": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    }  },  "deletedAt": "2026-08-03T08:15:00Z"}

代码仓库推送

EVENTrepository.pushed

一次原子推送，可能同时更新多个引用。没有 commits 数组；每个引用更新仅附带尽力提供的 tip 元数据。

负载字段

repository 对象

本次推送的目标代码仓库。

repository.id string

repository.name string

repository.owner 对象

仓库的所有者。

repository.owner.slug string

所有者的唯一 URL 友好名称。

repository.owner.id string

所有者 namespace 的唯一 ID。

repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

refUpdates 数组

本次推送包含的引用，上限为 100 个。

refUpdates[].ref string

所推送的完整 git 引用。示例：refs/heads/main 或 refs/tags/v3.14.1。

refUpdates[].before string

推送前 ref 上最近一次提交的 SHA。若该引用是刚刚创建的，则为全零 (0000000000000000000000000000000000000000) 。

refUpdates[].after string

推送后 ref 上最新 commit 的 SHA。若该引用已被删除，则为全零 (0000000000000000000000000000000000000000) 。

refUpdates[].created boolean

此次推送是否创建了该引用。

refUpdates[].deleted 布尔值

此次推送是否删除了该引用。

refUpdates[].forced 布尔值

此次推送是否重写了历史：即对已有 ref 的非 fast-forward 更新 (新的 tip 不是旧 tip 的后代) 。对于 ref 的创建、删除、fast-forward 更新，以及 Origin 开始跟踪强制推送状态之前观测到的推送，此值为 False。

refUpdates[].headCommit 对象

剥离后新 tip 所指向 commit 的元数据 (尽力提供) 。删除操作、非 commit 引用、历史推送以及提取失败时，该字段为未设置。

refUpdates[].headCommit.sha string

refUpdates[].headCommit.author 对象

commit 的 author 或 committer 的 Git 身份标识与时间戳。这是记录在 commit object 中的身份标识，而非已关联的用户账户。

refUpdates[].headCommit.author.name string

refUpdates[].headCommit.author.email string

refUpdates[].headCommit.author.date string

ISO-8601 时间戳，保留 git 签名的原始时区偏移 (例如 "2014-11-07T22:01:45+01:00") 。

refUpdates[].headCommit.committer 对象

commit 的 author 或 committer 的 Git 身份标识和时间戳。这是记录在 commit object 中的身份标识，而非已关联的用户账户。

refUpdates[].headCommit.committer.name string

refUpdates[].headCommit.committer.email string

refUpdates[].headCommit.committer.date string

ISO-8601 时间戳，保留 git 签名的原始时区偏移 (例如 "2014-11-07T22:01:45+01:00") 。

refUpdates[].headCommit.message string

pushedAt string

Origin 检测到该推送的时间。RFC 3339 时间戳。

pusher 对象

执行此次推送的 principal，由 Origin 验证。若推送由 Origin 自身执行，则该字段不存在，例如 PR 合并时推进 base ref 的那次合并推送。

pusher.user object

pusher.user.id string

pusher.user.email string 必填

pusher.user.displayName string

人类可读的显示名称：账户的名与姓，各自去除首尾空白后以空格连接，与产品 UI 中显示的名称完全一致。账户没有名称时省略该字段；绝不会由电子邮件、id 或其他任何字段拼凑生成。若 webhook 负载中的操作者无法解析，该字段也可能不存在。

pusher.user.handle string

用户已认领的个人资料 handle (cursor.com /@handle 背后的身份标识) ，不含 @ 前缀。仅当用户的个人资料处于公开可见状态时才会返回；对于未认领 handle 的用户以及非公开的个人资料，该字段将被省略。

pusher.app 对象

pusher.app.id string

pusher.app.displayName string

应用注册的显示名称，存在时不会为空。若负载所属应用无法解析，或 actor 为 Cursor 第一方门面 actor，则省略该字段。

pusher.serviceAccount 对象

pusher.serviceAccount.id string

refUpdatesCount 整数

本次原子推送中的引用更新数量。若生产方对列表做了截断，ref_updates 可能会更短。

event.payload 示例：

{  "repository": {    "id": "repo_01k2ja2000e0080000000000q4",    "name": "rocket",    "owner": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    }  },  "refUpdates": [    {      "ref": "refs/heads/add-telemetry",      "before": "5c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d",      "after": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",      "created": false,      "deleted": false,      "forced": false,      "headCommit": {        "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",        "author": {          "name": "Jane Doe",          "email": "jane@acme.dev",          "date": "2026-08-01T09:30:00Z"        },        "committer": {          "name": "Jane Doe",          "email": "jane@acme.dev",          "date": "2026-08-01T09:30:00Z"        },        "message": "Add launch telemetry"      }    }  ],  "pushedAt": "2026-08-02T14:45:00Z",  "pusher": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  },  "refUpdatesCount": 1}

代码仓库元数据已更新

EVENTrepository.metadata.updated

包含完整的代码仓库 snapshot，不含 delta，也没有执行更新的 actor。可对比前后两次 snapshot，或重新 fetch 该代码仓库，以查看发生了哪些变更。

负载字段

repository 对象

更新后的完整代码仓库快照。

repository.id string

repository.name string 必填

仓库名称，在其所有者下唯一。创建时必填。

repository.fullName string

"{owner.login}/{name}"。自动派生。

repository.owner 对象

所有者实体。创建时由 parent 决定，不可直接设置。

repository.owner.slug string

所有者的唯一 URL 友好名称。

repository.owner.id string

所属 namespace 的唯一 ID。

repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

repository.defaultBranch string

默认分支名称。响应中始终会返回该字段。创建时若省略此字段或留空，则默认为 "main"。

repository.createdAt string

RFC 3339 格式的 timestamp。

repository.updatedAt string

RFC 3339 格式的 timestamp。

repository.pushedAt string

任意分支上最近一次推送的时间戳；首次推送前不返回该字段。RFC 3339 格式时间戳。

repository.cloneUrl string

用于克隆该代码仓库的 HTTPS URL。

repository.mirror 对象

镜像元数据。原生代码仓库不包含该字段；镜像在初次同步完成前也不会返回该字段。

repository.mirror.source string

取值之一：github。

repository.mirror.sourceId string

由来源分配的不透明代码仓库标识符。

repository.mirror.status string

过渡期间的实际生效方向，直至切换完成。取值为 inbound 或 outbound。

repository.visibility string

代码仓库可见性，internal 或 private。取值为 internal、private 之一。

repository.allowMergeCommit boolean

PR 是否可以以 merge 提交的方式合入。

repository.allowSquashMerge boolean

PR 是否可以通过 squash merge 方式合入。

repository.deleteBranchOnMerge boolean

merge 时是否自动删除 head 分支。

event.payload 示例：

{  "repository": {    "id": "repo_01k2ja2000e0080000000000q4",    "name": "rocket",    "fullName": "acme/rocket",    "owner": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    },    "defaultBranch": "release",    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-03T08:15:00Z",    "cloneUrl": "https://origin.cursor.com/git/acme/rocket.git",    "pushedAt": "2026-08-02T14:45:00Z"  }}

拉取请求事件

EVENTpull_request.createdpull_request.publishedpull_request.reopenedpull_request.closedpull_request.mergedpull_request.metadata.updatedpull_request.head_ref.pushedpull_request.base_ref.updated

PR 生命周期变更。生命周期操作即信封的 event.type，没有单独的 action 字段。

负载字段

pullRequest object

PR 快照。其中不含已分配的标签；请通过 GetPullRequest 读取。

pullRequest.id string

稳定的 Origin PR 标识符。

pullRequest.number string

该 PR 在其代码仓库中的编号。

pullRequest.state string

"open" 或 "closed"。草稿状态为 "open"；已合并和已关闭的拉取请求均为 "closed"。

pullRequest.draft boolean

该 PR 是否仍为草稿。

pullRequest.merged boolean

该 PR 是否已合并。

pullRequest.title string

PR 标题。

pullRequest.body string

PR 描述。

pullRequest.head object

拉取请求的源端——即要被合并进去的内容。

pullRequest.head.ref string

该侧指向的引用，以 Origin 记录的为准。

pullRequest.head.sha string

该 change 最新 version 中此侧的 tip commit SHA。

pullRequest.base object

PR 的目标端，即要合入的分支。

pullRequest.base.ref string

此侧指向的引用，即 Origin 所记录的值。

pullRequest.base.sha string

该 change 最新 version 下此侧的 tip commit SHA。

pullRequest.author 对象

创建该 PR 的 principal。

pullRequest.author.user 对象

pullRequest.author.user.id string

pullRequest.author.user.email string 必填

pullRequest.author.user.displayName string

易读的显示名称：账户的名与姓，各自去除首尾空格后以空格连接，与产品 UI 中显示的名称完全一致。账户没有名称时省略该字段；绝不会根据电子邮件、id 或其他任何字段拼凑生成。对于无法解析出 actor 的 webhook 负载，该字段也可能不存在。

pullRequest.author.user.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 背后的身份标识) ，不含 @ 前缀。仅当用户的个人资料公开可见时才会出现；对于未认领 handle 的用户以及非公开个人资料，该字段会被省略。

pullRequest.author.app 对象

pullRequest.author.app.id string

pullRequest.author.app.displayName string

应用注册的显示名称，存在时必不为空。当负载所属应用无法解析时，以及对于第一方 Cursor 门面 actor，此字段会被省略。

pullRequest.author.serviceAccount object

pullRequest.author.serviceAccount.id string

pullRequest.createdAt string

PR 的创建时间。RFC 3339 时间戳。

pullRequest.updatedAt string

PR 最后更新的时间。RFC 3339 时间戳。

pullRequest.closedAt string

拉取请求关闭或合并的时间；处于打开状态时该字段未设置。RFC 3339 时间戳。

pullRequest.mergedAt string

PR 的合并时间；未合并时该字段为空。RFC 3339 时间戳。

pullRequest.mergeCommitSha string

生成的合并提交的 SHA；合并后即会设置。

pullRequest.additions 整数

该拉取请求最新版本新增的行数。

pullRequest.deletions 整数

该 PR 最新版本删除的行数。

pullRequest.changedFiles 整数

该 PR 最新版本所改动的文件。

pullRequest.version object

该 PR 的最新版本。

pullRequest.version.number string

change 内单调递增的 version 编号 (从 1 开始) 。

pullRequest.version.headSha string

此版本的头部提交 SHA。

pullRequest.version.baseSha string

该版本进行 diff 对比时所基于的基准 commit SHA。

pullRequest.version.createdAt string

该版本的创建时间。RFC 3339 时间戳。

repository object

该 PR 所属的代码仓库。

repository.id string

repository.name string

repository.owner 对象

仓库的所有者。

repository.owner.slug string

owner 的唯一 URL 友好名称。

repository.owner.id string

所属 namespace 的唯一 ID。

repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

event.payload 示例：

{  "pullRequest": {    "id": "pr_01k2ja2000e0080000000000d4",    "number": "17",    "state": "open",    "draft": false,    "merged": false,    "title": "Add launch telemetry",    "body": "Adds structured launch telemetry to the ignition path.",    "head": {      "ref": "add-telemetry",      "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4"    },    "base": {      "ref": "main",      "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"    },    "author": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "jane@acme.dev"      }    },    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T14:45:00Z",    "additions": 128,    "deletions": 46,    "changedFiles": 5,    "version": {      "number": "3",      "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",      "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",      "createdAt": "2026-08-01T09:30:00Z"    }  },  "repository": {    "id": "repo_01k2ja2000e0080000000000q4",    "name": "rocket",    "owner": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    }  }}

拉取请求评论

EVENTpull_request.comment.created

在 PR 上创建的评论。随评审一同提交的评论会在评审提交时发送，每条评论对应一个事件。

负载字段

pullRequest object

该评论所在的 PR。

pullRequest.id string

不可变的 Origin change id。

pullRequest.number string

pullRequest.repository 对象

该 PR 所属的代码仓库引用。

pullRequest.repository.id string

pullRequest.repository.name string

pullRequest.repository.owner object

仓库的所有者。

pullRequest.repository.owner.slug string

所有者的唯一名称，适用于 URL。

pullRequest.repository.owner.id string

所属 namespace 的唯一 ID。

pullRequest.repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

comment object

所创建的评论。开启线程的评论会内联携带该线程的 diff 锚点；回复仅携带 comment.thread.id。线程的解决状态不属于该事件，需通过 GetPullRequestComment 读取。

comment.id string

comment.thread 对象

该评论所属的线程，包含其 diff 锚点和解决状态。

comment.thread.id string

comment.thread.version 对象

该线程所针对的 PR 版本，包含其 head 和 base 的 SHA (参见 PullRequestReview.pull_request_version) 。

comment.thread.version.number string

change 内单调递增的 version 编号 (从 1 开始) 。

comment.thread.version.headSha string

该版本的头部提交 SHA。

comment.thread.version.baseSha string

该版本用于 diff 对比的基准 commit SHA。

comment.thread.version.createdAt string

此 version 的创建时间。RFC 3339 timestamp。

comment.thread.path string

线程 diff anchor 所在的文件路径。通用讨论线程为空。

comment.thread.side string

锚点所在的 diff 一侧。普通讨论线程不设置该值。取值为 left 或 right。

comment.thread.startLine integer

文件 side 版本中锚定范围的起始行。文件级线程和一般讨论线程为 0。

comment.thread.endLine 整数

锚定范围的最后一行 (包含该行) 。当锚点为单行或没有行范围时为 0。

comment.thread.resolvedAt string

线程解决的时间。线程处于打开状态时该值未设置。RFC 3339 时间戳。

comment.thread.createdAt string

RFC 3339 格式的 timestamp。

comment.thread.updatedAt string

RFC 3339 格式的 timestamp。

comment.body string

comment.author 对象

执行了外部可见操作的用户、应用或服务账户。

comment.author.user object

comment.author.user.id string

comment.author.user.email string 必填

comment.author.user.displayName string

便于人阅读的显示名称：账户的名与姓各自去除首尾空格后以空格连接——与产品 UI 中呈现的名称完全一致。账户没有姓名时将省略该字段；绝不会由电子邮件、id 或其他任何字段拼凑生成。对于无法解析出 actor 的 webhook 负载，该字段也可能不存在。

comment.author.user.handle string

用户已认领的个人资料 handle (cursor.com /@handle 所对应的身份标识) ，不含 @ 前缀。仅当用户的个人资料处于公开可见状态时才会出现；未认领 handle 的用户以及非公开个人资料将省略该字段。

comment.author.app 对象

comment.author.app.id string

comment.author.app.displayName string

应用注册的显示名称，存在时必不为空。若负载所属应用无法解析，或为第一方 Cursor 门面 actor，则会省略该字段。

comment.author.serviceAccount 对象

comment.author.serviceAccount.id string

comment.createdAt string

RFC 3339 格式的 timestamp。

comment.updatedAt string

RFC 3339 格式的 timestamp。

event.payload 示例：

{  "pullRequest": {    "id": "pr_01k2ja2000e0080000000000d4",    "number": "17",    "repository": {      "id": "repo_01k2ja2000e0080000000000q4",      "name": "rocket",      "owner": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      }    }  },  "comment": {    "id": "cmt_01k2ja2000e0080000000000e5",    "thread": {      "id": "cth_01k2ja2000e0080000000000s6",      "version": {        "number": "3",        "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",        "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",        "createdAt": "2026-08-01T09:30:00Z"      },      "path": "src/telemetry/retry.ts",      "side": "right",      "startLine": 42,      "endLine": 45,      "createdAt": "2026-08-01T09:30:00Z",      "updatedAt": "2026-08-02T14:45:00Z"    },    "body": "Should the retry budget be configurable?",    "author": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "jane@acme.dev"      }    },    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T14:45:00Z"  }}

拉取请求评审事件

EVENTpull_request.review.submittedpull_request.review.dismissed

负载字段

pullRequest 对象

该评审所针对的 PR。

pullRequest.id string

不可变的 Origin change id。

pullRequest.number string

pullRequest.repository 对象

此 PR 所属的代码仓库引用。

pullRequest.repository.id string

pullRequest.repository.name string

pullRequest.repository.owner 对象

仓库的所有者。

pullRequest.repository.owner.slug string

所有者的唯一 URL 友好名称。

pullRequest.repository.owner.id string

所有者 namespace 的唯一 ID。

pullRequest.repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

review 对象

已提交或已撤销的评审。撤销时会设置 review.dismissal。

review.id string

稳定的 Origin 评审标识符。

review.author 对象

发起该评审的 principal。

review.author.user 对象

review.author.user.id string

review.author.user.email string 必填

review.author.user.displayName string

便于阅读的显示名称：账户的名与姓，各自去除首尾空格后以空格连接——与产品 UI 中显示的名称完全一致。账户没有名称时省略该字段；绝不会根据电子邮件、id 或其他任何字段拼凑生成。对于无法解析出操作者的 webhook 负载，该字段也可能不存在。

review.author.user.handle string

用户已认领的个人资料 handle (cursor.com /@handle 背后的身份标识) ，不含 @ 前缀。仅当用户的个人资料处于公开可见状态时才会出现；对于未认领 handle 的用户以及非公开的个人资料，将省略该字段。

review.author.app 对象

review.author.app.id string

review.author.app.displayName string

应用注册的显示名称，存在时绝不为空。若负载所属应用无法解析，或来自第一方 Cursor 外观层 actor，则会省略该字段。

review.author.serviceAccount 对象

review.author.serviceAccount.id string

review.verdict string

取值为 approve、request_changes、comment 之一。

review.body string

自由文本形式的评审摘要。若审阅人未填写摘要，则为空。

review.submittedAt string

评审的提交时间。若为尚未提交的草稿评审，则该值未设置。RFC 3339 时间戳。

review.pullRequestVersion 对象

该决定适用的 PR 版本和 head SHA。

review.pullRequestVersion.number string

该 change 内单调递增的版本号 (从 1 开始) 。

review.pullRequestVersion.headSha string

此版本的头部提交 SHA。

review.pullRequestVersion.baseSha string

该版本进行 diff 对比时所基于的 base commit SHA。

review.pullRequestVersion.createdAt string

该版本的创建时间。RFC 3339 时间戳。

review.dismissal 对象

评审被驳回后即设置该值；当该决定仍计入 PR 的评审状态时，此字段不存在。

review.dismissal.dismissedBy 对象

驳回该评审的主体。若该驳回记录所属的操作者类型未由本 API 公开，则此字段不存在。

review.dismissal.dismissedBy.user 对象

review.dismissal.dismissedBy.user.id string

review.dismissal.dismissedBy.user.email string 必填

review.dismissal.dismissedBy.user.displayName string

人类可读的显示名称：账户的名与姓，各自去除首尾空格后以空格连接，与产品 UI 中呈现的名称完全一致。账户没有姓名时省略该字段；绝不会根据电子邮件、id 或其他任何字段拼凑生成。对于无法解析出操作者的 webhook 负载，该字段也可能不存在。

review.dismissal.dismissedBy.user.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 所对应的身份标识) ，不含 @ 前缀。仅当用户的个人资料公开可见时才会出现；对于未认领 handle 的用户以及非公开个人资料，该字段会被省略。

review.dismissal.dismissedBy.app 对象

review.dismissal.dismissedBy.app.id string

review.dismissal.dismissedBy.app.displayName string

应用注册的显示名称，存在时绝不为空。若负载所属应用无法解析，或为 Cursor 第一方门面 actor，则省略该字段。

review.dismissal.dismissedBy.serviceAccount 对象

review.dismissal.dismissedBy.serviceAccount.id string

review.dismissal.dismissedAt string

评审被驳回的时间，为 RFC 3339 时间戳。

review.dismissal.message string

撤销时记录的原因。若评审因作者提交了更新的决定而被自动作废，则会附带服务器生成的原因。

event.payload 示例：

{  "pullRequest": {    "id": "pr_01k2ja2000e0080000000000d4",    "number": "17",    "repository": {      "id": "repo_01k2ja2000e0080000000000q4",      "name": "rocket",      "owner": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      }    }  },  "review": {    "id": "rev_01k2ja2000e0080000000000f6",    "author": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "jane@acme.dev"      }    },    "verdict": "approve",    "body": "Approving. The telemetry schema matches the spec.",    "submittedAt": "2026-08-02T15:00:00Z",    "pullRequestVersion": {      "number": "3",      "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",      "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",      "createdAt": "2026-08-01T09:30:00Z"    }  }}

拉取请求审阅人事件

EVENTpull_request.reviewer.addedpull_request.reviewer.removedpull_request.reviewer.rerequested

PR 的请求审阅人发生变更。可使用 ListPullRequestRequestedReviewers 读取当前待评审的审阅人集合。

负载字段

pullRequest 对象

请求的审阅人发生变更的 PR。

pullRequest.id string

不可变的 Origin change id。

pullRequest.number string

pullRequest.repository 对象

此 PR 所属的代码仓库引用。

pullRequest.repository.id string

pullRequest.repository.name string

pullRequest.repository.owner object

仓库的所有者。

pullRequest.repository.owner.slug string

所有者的唯一名称，适用于 URL。

pullRequest.repository.owner.id string

所属 namespace 的唯一 ID。

pullRequest.repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

reviewer 对象

该事件所涉及的被请求审阅人。

reviewer.user 对象

reviewer.user.id string

reviewer.user.email string 必填

reviewer.user.displayName string

便于阅读的显示名称：账户的名与姓，各自去除首尾空格后以空格连接，与产品 UI 中呈现的名称完全一致。账户没有名称时省略该字段；绝不会根据电子邮件、id 或任何其他字段拼凑生成。对于无法解析出操作者的 webhook 负载，该字段也可能不存在。

reviewer.user.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 所对应的身份) ，不含 @ 前缀。仅当用户的个人资料处于公开可见状态时才会出现；对于未认领 handle 的用户以及非公开个人资料，该字段将被省略。

reviewer.group 对象

公开的 Origin 群组标识 (grp_…) 。目前仅含 id。

reviewer.group.id string

createdVia string

评审请求的创建方式。取值为 manual、codeowners 之一。

createdBy object

创建该评审请求的主体 (若已知) 。

createdBy.user object

createdBy.user.id string

createdBy.user.email string 必填

createdBy.user.displayName string

易读的显示名称：账户的名与姓，各自去除首尾空格后以空格连接，与产品 UI 中呈现的名称完全一致。账户没有姓名时省略该字段；绝不会根据电子邮件、id 或其他任何字段拼凑生成。对于无法解析出操作者的 webhook 负载，该字段也可能不存在。

createdBy.user.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 背后的身份标识) ，不含 @ 前缀。仅当用户的个人资料处于公开可见状态时才会返回；对于未认领 handle 的用户以及非公开个人资料，该字段将被省略。

createdBy.app 对象

createdBy.app.id string

createdBy.app.displayName string

应用注册的显示名称，存在时必定非空。对于无法解析出应用的负载，以及第一方 Cursor 门面 actor，此字段会被省略。

createdBy.serviceAccount 对象

createdBy.serviceAccount.id string

createdAt string

评审请求的创建时间。RFC 3339 时间戳。

event.payload 示例：

{  "pullRequest": {    "id": "pr_01k2ja2000e0080000000000d4",    "number": "17",    "repository": {      "id": "repo_01k2ja2000e0080000000000q4",      "name": "rocket",      "owner": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      }    }  },  "reviewer": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  },  "createdVia": "codeowners",  "createdAt": "2026-08-02T14:45:00Z"}

Check Run 事件

EVENTrepository.check_run.createdrepository.check_run.completed

Origin check-run 生命周期事件的已提交快照。

负载字段

repository 对象

该 check run 所属的代码仓库。

repository.id string

repository.name string

repository.owner 对象

仓库的所有者。

repository.owner.slug string

所有者的唯一名称，适用于 URL。

repository.owner.id string

所属命名空间的唯一 ID。

repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team 或 user。

checkSuite 对象

该 check run 所属的 suite。

checkSuite.id string

由服务器分配的套件唯一 ID。

checkSuite.repository 对象

该测试套件所属的代码仓库。

checkSuite.repository.id string

checkSuite.repository.name string

checkSuite.repository.owner 对象

仓库的所有者。

checkSuite.repository.owner.slug string

所有者的唯一 URL 友好名称。

checkSuite.repository.owner.id string

所属命名空间的唯一 ID。

checkSuite.repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team 或 user。

checkSuite.sha string

该 suite 所关联的已解析头部提交 SHA (小写 hex) 。

checkSuite.key string

由应用为该测试套件选择的幂等键 (idempotency key) 。

checkSuite.name string

面向用户的套件名称。

checkSuite.detailsUrl string

指向整个 suite 更多详情的链接 (如已设置) 。

checkSuite.createdAt string

RFC 3339 格式的时间戳。

checkSuite.updatedAt string

RFC 3339 格式的 timestamp。

checkSuite.externalId string

提供者为此次 suite 尝试分配的不可变标识。

checkSuite.actor 对象

生成该套件的主体。

checkSuite.actor.user 对象

checkSuite.actor.user.id string

checkSuite.actor.user.email 字符串 必填

checkSuite.actor.user.displayName string

便于阅读的显示名称：账户的名和姓各自去除首尾空格后以空格连接而成，与产品 UI 中呈现的名称完全一致。账户没有姓名时省略；绝不会根据电子邮件、id 或其他任何字段拼凑生成。若 webhook 负载中的操作者无法解析，该字段也可能不存在。

checkSuite.actor.user.handle string

用户已认领的个人资料 handle (即 cursor.com/@handle 所对应的身份标识) ，不含 @ 前缀。仅在用户个人资料公开可见时返回；未认领 handle 的用户以及非公开个人资料将省略该字段。

checkSuite.actor.app 对象

checkSuite.actor.app.id string

checkSuite.actor.app.displayName string

应用注册的显示名称，存在时不会为空。当对应应用无法解析，或对于第一方 Cursor facade actor 时会在负载中省略该字段。

checkSuite.actor.serviceAccount 对象

checkSuite.actor.serviceAccount.id string

checkRun object

该生命周期阶段的检查运行快照。

checkRun.id string

由服务器分配的检查运行唯一 ID。

checkRun.repository 对象

该检查运行所属的仓库。

checkRun.repository.id string

checkRun.repository.name string

checkRun.repository.owner 对象

仓库的所有者。

checkRun.repository.owner.slug string

适用于 URL 的所有者唯一名称。

checkRun.repository.owner.id string

所属命名空间的唯一 ID。

checkRun.repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

checkRun.checkSuite 对象

该 check run 所属的 suite。

checkRun.checkSuite.id string

checkRun.sha string

该 check run 所关联的已解析 head 提交 SHA (小写十六进制) 。

checkRun.key string

由 app 为该 check run 指定的幂等键。

checkRun.name string

面向用户展示的 check-run 名称。

checkRun.status string

生命周期状态。rerequested 表示已完成的 run 已被请求重新运行，但所属应用尚未响应：对读取方而言处于待处理状态 (呈现如 queued) ，conclusion 和时间信息仍描述被取代的尝试。仅可由 Origin 在重新请求时 (RerequestCheckRun) 设置；应用无法发布此状态。取值为 queued、in_progress、completed、rerequested 之一。

checkRun.conclusion string

仅当 status 为 completed 或 rerequested 时存在。对于 rerequested 的 run，它表示被取代尝试的裁决：应将该 run 视为挂起，仅当 status == completed 时读取 conclusion。取值为 success、failure、neutral、cancelled、skipped、timed_out、action_required 或 stale。

checkRun.detailsUrl string

指向该 check run 详情的链接 (如已设置) 。

checkRun.externalUpdatedAt string

外部系统的最后更新时间，用于排序。RFC 3339 格式的时间戳。

checkRun.startedAt string

检查运行的开始时间 (如已报告) 。RFC 3339 时间戳。

checkRun.completedAt string

check run 完成的时间 (若有上报) 。RFC 3339 时间戳。

checkRun.createdAt string

RFC 3339 格式的时间戳。

checkRun.updatedAt string

RFC 3339 格式的时间戳。

checkRun.externalId string

由提供者为此检查尝试分配的不可变标识 (参见 CheckRunInput.external_id：建议每次执行使用一个) 。

checkRun.actor object

生成该检查运行的主体 (Principal) 。

checkRun.actor.user 对象

checkRun.actor.user.id string

checkRun.actor.user.email string 必填

checkRun.actor.user.displayName string

便于阅读的显示名称：账户的名和姓各自去除首尾空格后以空格连接而成，与产品 UI 中呈现的名称完全一致。账户没有姓名时省略；绝不会根据电子邮件、id 或其他任何字段拼凑生成。若 webhook 负载中的操作者无法解析，该字段也可能不存在。

checkRun.actor.user.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 所对应的身份标识)，不含 @ 前缀。仅当用户的个人资料处于公开可见状态时才会返回；未认领 handle 的用户以及非公开个人资料将省略该字段。

checkRun.actor.app 对象

checkRun.actor.app.id string

checkRun.actor.app.displayName string

应用注册的显示名称，存在时不会为空。若负载对应的应用无法解析，或对于 Cursor 第一方门面 actor，则省略该字段。

checkRun.actor.serviceAccount 对象

checkRun.actor.serviceAccount.id string

checkRun.output object

该检查运行的人类可读输出 (如果已设置) 。

checkRun.output.title string

输出的简短标题。最大长度：255 个字符。

checkRun.output.summary string

输出的摘要。可包含 Markdown。UTF-8 最大长度：65535 字节。

checkRun.output.text string

详细输出。可包含 Markdown。UTF-8 最大大小：65535 字节。

checkRun.deadlineAt string

可选的截止时间。省略或未设置表示没有到期。RFC 3339 时间戳。

checkRun.isRerequestable boolean

上报的 app 是否将该 run 声明为可重新请求 (CheckRunInput.is_rerequestable) 。

checkRun.rerequestedAt string

在重新请求仍然未完成时设置；当提供者再次提交时清除。未设置表示没有待处理的重新请求。设置期间，status 为 rerequested，该 run 在提交的 CI 状态中保持为 pending (conclusion 和时间信息为被取代的结果) ；所属应用通过发布其承诺的 run 来响应，声明 is_rerequestable——可以是相同 key 的新 run，或对该 run 的更新 (会清除此字段) ——之后该 run 可再次被重新请求。RFC 3339 时间戳。

checkRun.rerequestedBy 对象

重新请求该 run 的 principal。仅当设置了 rerequested_at 时存在；当所属 app 作出响应时，二者一并清除。

checkRun.rerequestedBy.user 对象

checkRun.rerequestedBy.user.id string

checkRun.rerequestedBy.user.email 字符串 必填

checkRun.rerequestedBy.user.displayName string

便于阅读的显示名称：由账户的名和姓各自去除首尾空格后以空格连接而成，与产品 UI 中呈现的名称完全一致。账户没有姓名时省略；绝不会根据电子邮件、id 或其他任何字段合成。若 webhook 负载的操作者无法解析，该字段也可能不存在。

checkRun.rerequestedBy.user.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 所对应的身份标识)，不含 @ 前缀。仅当用户的个人资料处于公开可见状态时才会返回；未认领 handle 的用户以及非公开个人资料将省略该字段。

checkRun.rerequestedBy.app 对象

checkRun.rerequestedBy.app.id string

checkRun.rerequestedBy.app.displayName string

应用注册的显示名称，存在时不会为空。当应用无法解析或对于第一方 Cursor facade actor 时，该字段会被省略。

checkRun.rerequestedBy.serviceAccount 对象

checkRun.rerequestedBy.serviceAccount.id string

actor object

生成该 check run 的 principal。

actor.user 对象

actor.user.id string

actor.user.email string 必填

actor.user.displayName string

便于阅读的显示名称：由账户的名和姓各自去除首尾空格后以空格连接而成，与产品 UI 中呈现的名称完全一致。账户没有姓名时省略该字段；绝不会根据电子邮件、id 或其他任何字段拼凑生成。若 webhook 负载的操作者无法解析，该字段也可能不存在。

actor.user.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 所对应的身份标识) ，不含 @ 前缀。仅当用户的个人资料公开可见时返回；未认领 handle 的用户以及非公开个人资料将省略该字段。

actor.app 对象

actor.app.id string

actor.app.displayName string

应用注册的显示名称，存在时不会为空。若负载对应的应用无法解析，或对于第一方 Cursor 门面 actor，则省略该字段。

actor.serviceAccount 对象

actor.serviceAccount.id string

event.payload 示例：

{  "repository": {    "id": "repo_01k2ja2000e0080000000000q4",    "name": "rocket",    "owner": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    }  },  "checkSuite": {    "id": "crg_01k2ja2000e0080000000000h8",    "repository": {      "id": "repo_01k2ja2000e0080000000000q4",      "name": "rocket",      "owner": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      }    },    "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "key": "ci-8842",    "name": "CI",    "detailsUrl": "https://ci.acme.dev/runs/8842",    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T14:45:00Z",    "externalId": "build-8842",    "actor": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "jane@acme.dev"      }    }  },  "checkRun": {    "id": "cr_01k2ja2000e0080000000000g7",    "repository": {      "id": "repo_01k2ja2000e0080000000000q4",      "name": "rocket",      "owner": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      }    },    "checkSuite": {      "id": "crg_01k2ja2000e0080000000000h8"    },    "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "key": "ci-8842-unit-tests",    "name": "unit-tests",    "status": "completed",    "conclusion": "success",    "detailsUrl": "https://ci.acme.dev/runs/8842",    "externalUpdatedAt": "2026-08-02T14:44:30Z",    "startedAt": "2026-08-02T14:40:00Z",    "completedAt": "2026-08-02T14:44:30Z",    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T14:45:00Z",    "externalId": "run-8842",    "actor": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "jane@acme.dev"      }    },    "output": {      "title": "Unit tests",      "summary": "128 tests passed.",      "text": "All suites green."    }  },  "actor": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  }}

检查运行已被重新请求

EVENTrepository.check_run.rerequested

repository.check_run.rerequested webhook 负载，仅投递给拥有该 check run 的应用。响应方式是针对同一 head SHA 与 key 发布一个新的 run —— 可以是全新的 run (新的 external_id) ，也可以是对被重新请求的 run 的更新。已打标的 run 会显示 status: rerequested (其 conclusion 和时间信息为已被取代的结果) ，直到响应的提交清除 rerequested_at。每次被接受的再次请求都会发出一个事件，且 run 在被响应后仍可再次被重新请求，因此仅凭事件 id 对重投递进行去重；check_run.rerequested_at 记录当前未处理的标记。负载中不含拉取请求 (PR) 上下文 (check run 关联到 (repository, sha)) ：需要 PR 的消费者可通过自身的 head 映射从 check_run.sha 解析出 PR，或使用按其构建的 head 分支过滤的 ListPullRequests。

负载字段

repository 对象

该检查运行所属的仓库。

repository.id string

repository.name string

repository.owner 对象

仓库的所有者。

repository.owner.slug string

所有者的唯一 URL 友好名称。

repository.owner.id string

所属 namespace 的唯一 ID。

repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

checkSuite 对象

该 check run 所属的 suite。

checkSuite.id string

由服务器分配的套件唯一 ID。

checkSuite.repository 对象

该 suite 所属的代码仓库。

checkSuite.repository.id string

checkSuite.repository.name string

checkSuite.repository.owner 对象

仓库的所有者。

checkSuite.repository.owner.slug string

所有者的唯一适用于 URL 的名称。

checkSuite.repository.owner.id string

所属 namespace 的唯一 ID。

checkSuite.repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

checkSuite.sha string

该测试套件所关联的已解析的头部提交 SHA (小写十六进制) 。

checkSuite.key string

由应用为该 suite 选择的幂等键。

checkSuite.name string

面向用户的套件名称。

checkSuite.detailsUrl string

指向整个套件更多详情的链接 (如已设置) 。

checkSuite.createdAt string

RFC 3339 格式的时间戳。

checkSuite.updatedAt string

RFC 3339 格式的时间戳。

checkSuite.externalId string

由提供者分配的本次套件尝试的不可变身份。

checkSuite.actor 对象

生成该套件的主体。

checkSuite.actor.user 对象

checkSuite.actor.user.id string

checkSuite.actor.user.email string 必填

checkSuite.actor.user.displayName string

便于阅读的显示名称：账户的名和姓各自去除首尾空格后以空格连接而成——与产品 UI 呈现的名称完全一致。账户没有姓名时省略该字段；绝不会根据电子邮件、id 或其他任何字段拼凑生成。若 webhook 负载中的操作者无法解析，该字段也可能不存在。

checkSuite.actor.user.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 所对应的身份标识) ，不含 @ 前缀。仅当用户的个人资料处于公开可见状态时才返回；未认领 handle 的用户以及非公开个人资料将省略该字段。

checkSuite.actor.app 对象

checkSuite.actor.app.id string

checkSuite.actor.app.displayName string

应用注册的显示名称，存在时不会为空。若负载对应的应用无法解析，或对于第一方 Cursor 门面 actor，则省略该字段。

checkSuite.actor.serviceAccount 对象

checkSuite.actor.serviceAccount.id string

checkRun object

被重新请求的 check run (status: rerequested) ；check_run.rerequested_at 记录该时间戳，check_run.rerequested_by 记录发起请求的 principal。

checkRun.id string

由服务器分配的 check run 唯一 ID。

checkRun.repository 对象

该 check run 所属的代码仓库。

checkRun.repository.id string

checkRun.repository.name string

checkRun.repository.owner 对象

仓库的所有者。

checkRun.repository.owner.slug string

所有者的唯一名称，适用于 URL。

checkRun.repository.owner.id string

所属命名空间的唯一 ID。

checkRun.repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

checkRun.checkSuite 对象

该 check run 所属的 suite。

checkRun.checkSuite.id string

checkRun.sha string

该 check run 所关联的已解析头部提交 SHA (小写十六进制) 。

checkRun.key string

由 app 为该 check run 指定的 idempotency key。

checkRun.name string

面向用户展示的 check-run 名称。

checkRun.status string

生命周期状态。rerequested 表示某个已完成的 run 被请求重新运行，但所属应用尚未响应：对读取方而言处于 pending (渲染方式与 queued 相同) ，此时 conclusion 与各时间字段仍描述已被取代的那次尝试。该值仅由 Origin 在重新请求时 (RerequestCheckRun) 设置；应用无法提交该值。取值为 queued、in_progress、completed、rerequested 之一。

checkRun.conclusion string

仅当 status 为 completed 或 rerequested 时存在。对于 rerequested 的 run，它是已被取代的那次尝试的决定：应将该 run 视为 pending，仅在 status == completed 时读取 conclusion。取值为 success、failure、neutral、cancelled、skipped、timed_out、action_required、stale 之一。

checkRun.detailsUrl string

指向该 check run 详情的链接 (如已设置) 。

checkRun.externalUpdatedAt string

外部系统的最后更新时间，用于排序。RFC 3339 时间戳。

checkRun.startedAt string

check run 的开始时间 (若已上报) 。RFC 3339 时间戳。

checkRun.completedAt string

check run 完成的时间 (若已上报) 。RFC 3339 时间戳。

checkRun.createdAt string

RFC 3339 格式的时间戳。

checkRun.updatedAt string

RFC 3339 格式的时间戳。

checkRun.externalId string

由提供方为本次检查尝试分配的不可变身份标识 (参见 CheckRunInput.external_id：推荐做法是每次执行使用一个) 。

checkRun.actor object

生成该 check run 的 principal。

checkRun.actor.user 对象

checkRun.actor.user.id string

checkRun.actor.user.email string 必填

checkRun.actor.user.displayName string

便于阅读的显示名称：账户的名和姓各自去除首尾空格后以空格连接而成，与产品 UI 中呈现的名称完全一致。账户没有姓名时省略；绝不会根据电子邮件、id 或其他任何字段合成。若 webhook 负载中的执行者无法解析，该字段也可能不存在。

checkRun.actor.user.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 所对应的身份标识) ，不含 @ 前缀。仅在用户的个人资料对公众可见时返回；未认领 handle 的用户以及非公开个人资料将省略该字段。

checkRun.actor.app object

checkRun.actor.app.id string

checkRun.actor.app.displayName string

应用注册的显示名称，存在时不会为空。若负载对应的应用无法解析，或对于第一方 Cursor 门面 actor，则省略该字段。

checkRun.actor.serviceAccount 对象

checkRun.actor.serviceAccount.id string

checkRun.output object

该检查运行的人类可读输出 (如已设置) 。

checkRun.output.title string

输出的简短标题。最大长度：255 个字符。

checkRun.output.summary string

输出摘要。可包含 Markdown。UTF-8 最大长度：65535 字节。

checkRun.output.text string

详细输出。可包含 Markdown。UTF-8 最大大小：65535 字节。

checkRun.deadlineAt string

可选截止时间。省略或未设置表示无过期。RFC 3339 时间戳。

checkRun.isRerequestable boolean

上报该 run 的应用是否将其声明为可重新请求 (CheckRunInput.is_rerequestable) 。

checkRun.rerequestedAt string

在重新请求尚未完成期间设置；当提供者再次发布时清除。未设置表示没有挂起的重新请求。设置期间，status 为 rerequested，该 run 在该提交的 CI 状态中保持为 pending (conclusion 和时间信息为被取代的结果) ；所属应用通过发布其所提交的 run 并声明 is_rerequestable 来响应——可为相同 key 的新 run，或对该 run 的一次更新 (这将清除此字段) ——之后该 run 可再次被重新请求。RFC 3339 时间戳。

checkRun.rerequestedBy 对象

重新请求该 run 的 principal。仅当 rerequested_at 已设置时存在；所属 app 响应后会与其一同被清除。

checkRun.rerequestedBy.user 对象

checkRun.rerequestedBy.user.id string

checkRun.rerequestedBy.user.email string 必填

checkRun.rerequestedBy.user.displayName string

便于阅读的显示名称：账户的名和姓各自去除首尾空格后以空格连接而成——与产品 UI 呈现的名称完全一致。账户没有姓名时省略；绝不会根据电子邮件、ID 或其他任何字段合成。若 webhook 载荷中的执行者无法解析，该字段也可能不存在。

checkRun.rerequestedBy.user.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 所对应的身份标识) ，不含 @ 前缀。仅在用户的个人资料公开可见时才会返回；未认领 handle 的用户及非公开个人资料将省略该字段。

checkRun.rerequestedBy.app 对象

checkRun.rerequestedBy.app.id string

checkRun.rerequestedBy.app.displayName string

应用注册的显示名称，存在时不会为空。当对应的应用无法解析或为第一方 Cursor 外观 (facade) actor 时，该字段会被省略。

checkRun.rerequestedBy.serviceAccount 对象

checkRun.rerequestedBy.serviceAccount.id string

event.payload 示例：

{  "repository": {    "id": "repo_01k2ja2000e0080000000000q4",    "name": "rocket",    "owner": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    }  },  "checkSuite": {    "id": "crg_01k2ja2000e0080000000000h8",    "repository": {      "id": "repo_01k2ja2000e0080000000000q4",      "name": "rocket",      "owner": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      }    },    "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "key": "ci-8842",    "name": "CI",    "detailsUrl": "https://ci.acme.dev/runs/8842",    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T15:10:00Z",    "externalId": "build-8842",    "actor": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "jane@acme.dev"      }    }  },  "checkRun": {    "id": "cr_01k2ja2000e0080000000000g7",    "repository": {      "id": "repo_01k2ja2000e0080000000000q4",      "name": "rocket",      "owner": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      }    },    "checkSuite": {      "id": "crg_01k2ja2000e0080000000000h8"    },    "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "key": "ci-8842-unit-tests",    "name": "unit-tests",    "status": "rerequested",    "conclusion": "failure",    "detailsUrl": "https://ci.acme.dev/runs/8842",    "externalUpdatedAt": "2026-08-02T14:44:30Z",    "startedAt": "2026-08-02T14:40:00Z",    "completedAt": "2026-08-02T14:44:30Z",    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T15:10:00Z",    "externalId": "run-8842",    "actor": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "jane@acme.dev"      }    },    "output": {      "title": "Unit tests",      "summary": "1 of 129 tests failed.",      "text": "FAIL telemetry.spec.ts > flushes queued events on shutdown"    },    "isRerequestable": true,    "rerequestedAt": "2026-08-02T15:10:00Z",    "rerequestedBy": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "jane@acme.dev"      }    }  }}

安装已创建

EVENTinstallation.created

负载字段

installation 对象

事件发生时的安装快照。

installation.id string

installation.appId string

已安装应用的 identifier；与负载中的 app.id 取值相同。

installation.target 对象

仓库的所有者。

installation.target.slug string

所有者的唯一 URL 友好名称。

installation.target.id string

所属 namespace 的唯一 ID。

installation.target.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

installation.repoSelectionMode string

取值为 all 或 selected。

installation.repositories 数组

当 repository_selection 为 "all" 时为空。最多返回 5,000 条；实际总数请参见 repositories_count。

installation.repositories[].id string

installation.repositories[].name string

installation.repositories[].owner 对象

仓库的所有者。

installation.repositories[].owner.slug string

所有者的唯一 URL 友好名称。

installation.repositories[].owner.id string

所属 namespace 的唯一 ID。

installation.repositories[].owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

installation.scopes 数组

installation.repositoriesCount integer

实际总数；当 repository_selection 为 "all" 时为 0。

installation.createdAt string

RFC 3339 格式的 timestamp。

installation.updatedAt string

RFC 3339 格式的 timestamp。

installation.deletedAt string

RFC 3339 格式的 timestamp。

installation.suspendedAt string

安装处于暂停状态时会设置该字段；处于活跃状态时则不设置。RFC 3339 时间戳。

installation.installedBy 对象

最初安装该应用的用户。

installation.installedBy.id string

installation.installedBy.email string 必填

installation.installedBy.displayName string

便于阅读的显示名称：账户的名与姓各自去除首尾空白后以空格连接，与产品 UI 中呈现的名称完全一致。账户没有名称时省略该字段；绝不会根据电子邮件、id 或其他任何字段合成。若 webhook 负载的操作者无法解析，该字段也可能不存在。

installation.installedBy.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 所对应的身份标识) ，不含 @ 前缀。仅在用户的个人资料处于公开可见状态时才会返回；未认领 handle 的用户以及非公开个人资料会省略该字段。

app object

该安装所属的应用。

app.id string

app.displayName string

应用注册的显示名称，存在时绝不为空。若入队时的数据填充无法解析该应用，则省略此字段。

event.payload 示例：

{  "installation": {    "id": "inst_01k2ja2000e0080000000000b2",    "appId": "app_01k2ja2000e0080000000000a1",    "target": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    },    "repoSelectionMode": "selected",    "repositories": [      {        "id": "repo_01k2ja2000e0080000000000q4",        "name": "rocket",        "owner": {          "slug": "acme",          "id": "ns_01k2ja2000e0080000000000p3",          "type": "team"        }      }    ],    "scopes": [      "repository:contents:read",      "repository:pull_requests:read"    ],    "repositoriesCount": 1,    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-01T09:30:00Z",    "installedBy": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  },  "app": {    "id": "app_01k2ja2000e0080000000000a1",    "displayName": "CI Status Bot"  }}

安装已更新

EVENTinstallation.updated

负载字段

installation 对象

事件发生时的安装快照。

installation.id string

installation.appId string

已安装应用的标识符；与负载中的 app.id 取值相同。

installation.target 对象

仓库的所有者。

installation.target.slug string

所有者的唯一 URL 友好名称。

installation.target.id string

所属 namespace 的唯一 ID。

installation.target.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

installation.repoSelectionMode string

取值为 all 或 selected。

installation.repositories 数组

当 repository_selection 为 "all" 时为空。最多返回 5,000 条；实际总数请参见 repositories_count。

installation.repositories[].id string

installation.repositories[].name string

installation.repositories[].owner 对象

仓库的所有者。

installation.repositories[].owner.slug string

所有者的唯一 URL 友好名称。

installation.repositories[].owner.id string

所属 namespace 的唯一 ID。

installation.repositories[].owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

installation.scopes 数组

installation.repositoriesCount integer

实际总数；当 repository_selection 为 "all" 时为 0。

installation.createdAt string

RFC 3339 格式的 timestamp。

installation.updatedAt string

RFC 3339 格式的 timestamp。

installation.deletedAt string

RFC 3339 格式的 timestamp。

installation.suspendedAt string

安装处于暂停状态时会设置该字段；处于活跃状态时则不设置。RFC 3339 时间戳。

installation.installedBy object

最初安装该应用的用户。

installation.installedBy.id string

installation.installedBy.email string 必填

installation.installedBy.displayName string

便于阅读的显示名称：账户的名与姓各自去除首尾空白后以空格连接，与产品 UI 中呈现的名称完全一致。账户没有名称时省略该字段；绝不会根据电子邮件、id 或其他任何字段合成。若 webhook 负载的操作者无法解析，该字段也可能不存在。

installation.installedBy.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 所对应的身份标识) ，不含 @ 前缀。仅在用户的个人资料处于公开可见状态时才会返回；未认领 handle 的用户以及非公开个人资料会省略该字段。

app object

该安装所属的应用。

app.id string

app.displayName string

应用注册的显示名称，存在时绝不为空。若入队时的数据填充无法解析该应用，则省略此字段。

event.payload 示例：

{  "installation": {    "id": "inst_01k2ja2000e0080000000000b2",    "appId": "app_01k2ja2000e0080000000000a1",    "target": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    },    "repoSelectionMode": "selected",    "repositories": [      {        "id": "repo_01k2ja2000e0080000000000q4",        "name": "rocket",        "owner": {          "slug": "acme",          "id": "ns_01k2ja2000e0080000000000p3",          "type": "team"        }      }    ],    "scopes": [      "repository:contents:read",      "repository:pull_requests:read"    ],    "repositoriesCount": 1,    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T14:45:00Z",    "installedBy": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  },  "app": {    "id": "app_01k2ja2000e0080000000000a1",    "displayName": "CI Status Bot"  }}

安装已暂停

EVENTinstallation.suspended

负载字段

installation 对象

事件发生时的安装快照。

installation.id string

installation.appId string

已安装应用的标识符；与负载中的 app.id 取值相同。

installation.target 对象

仓库的所有者。

installation.target.slug string

所有者的唯一 URL 友好名称。

installation.target.id string

所属 namespace 的唯一 ID。

installation.target.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

installation.repoSelectionMode string

取值为 all 或 selected。

installation.repositories 数组

当 repository_selection 为 "all" 时为空。最多返回 5,000 条；实际总数请参见 repositories_count。

installation.repositories[].id string

installation.repositories[].name string

installation.repositories[].owner 对象

仓库的所有者。

installation.repositories[].owner.slug string

所有者的唯一 URL 友好名称。

installation.repositories[].owner.id string

所属 namespace 的唯一 ID。

installation.repositories[].owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

installation.scopes 数组

installation.repositoriesCount integer

实际总数；当 repository_selection 为 "all" 时为 0。

installation.createdAt string

RFC 3339 格式的 timestamp。

installation.updatedAt string

RFC 3339 格式的 timestamp。

installation.deletedAt string

RFC 3339 格式的 timestamp。

installation.suspendedAt string

安装处于暂停状态时会设置该字段；处于活跃状态时则不设置。RFC 3339 时间戳。

installation.installedBy object

最初安装该应用的用户。

installation.installedBy.id string

installation.installedBy.email string 必填

installation.installedBy.displayName string

便于阅读的显示名称：账户的名与姓各自去除首尾空白后以空格连接，与产品 UI 中呈现的名称完全一致。账户没有名称时省略该字段；绝不会根据电子邮件、id 或其他任何字段合成。若 webhook 负载的操作者无法解析，该字段也可能不存在。

installation.installedBy.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 所对应的身份标识)，不含 @ 前缀。仅在用户的个人资料处于公开可见状态时才会返回；未认领 handle 的用户以及非公开个人资料会省略该字段。

app object

该安装所属的应用。

app.id string

app.displayName string

应用注册的显示名称，存在时绝不为空。若入队时的数据填充无法解析该应用，则省略此字段。

event.payload 示例：

{  "installation": {    "id": "inst_01k2ja2000e0080000000000b2",    "appId": "app_01k2ja2000e0080000000000a1",    "target": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    },    "repoSelectionMode": "selected",    "repositories": [      {        "id": "repo_01k2ja2000e0080000000000q4",        "name": "rocket",        "owner": {          "slug": "acme",          "id": "ns_01k2ja2000e0080000000000p3",          "type": "team"        }      }    ],    "scopes": [      "repository:contents:read",      "repository:pull_requests:read"    ],    "repositoriesCount": 1,    "createdAt": "2026-08-01T09:30:00Z",    "installedBy": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    },    "suspendedAt": "2026-08-03T08:15:00Z"  },  "app": {    "id": "app_01k2ja2000e0080000000000a1",    "displayName": "CI Status Bot"  }}

安装已恢复

EVENTinstallation.unsuspended

负载字段

installation 对象

事件发生时的安装快照。

installation.id string

installation.appId string

已安装应用的标识符；与负载中的 app.id 取值相同。

installation.target 对象

仓库的所有者。

installation.target.slug string

所有者的唯一 URL 友好名称。

installation.target.id string

所属 namespace 的唯一 ID。

installation.target.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

installation.repoSelectionMode string

取值为 all 或 selected。

installation.repositories 数组

当 repository_selection 为 "all" 时为空。最多返回 5,000 条；实际总数请参见 repositories_count。

installation.repositories[].id string

installation.repositories[].name string

installation.repositories[].owner 对象

仓库的所有者。

installation.repositories[].owner.slug string

所有者的唯一 URL 友好名称。

installation.repositories[].owner.id string

所属 namespace 的唯一 ID。

installation.repositories[].owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

installation.scopes 数组

installation.repositoriesCount integer

实际总数；当 repository_selection 为 "all" 时为 0。

installation.createdAt string

RFC 3339 格式的 timestamp。

installation.updatedAt string

RFC 3339 格式的 timestamp。

installation.deletedAt string

RFC 3339 格式的 timestamp。

installation.suspendedAt string

安装处于暂停状态时会设置该字段；处于活跃状态时则不设置。RFC 3339 时间戳。

installation.installedBy object

最初安装该应用的用户。

installation.installedBy.id string

installation.installedBy.email string 必填

installation.installedBy.displayName string

便于阅读的显示名称：账户的名与姓各自去除首尾空白后以空格连接，与产品 UI 中呈现的名称完全一致。账户没有名称时省略该字段；绝不会根据电子邮件、id 或其他任何字段合成。若 webhook 负载的操作者无法解析，该字段也可能不存在。

installation.installedBy.handle string

用户已认领的个人资料 handle(即 cursor.com /@handle 所对应的身份标识),不含 @ 前缀。仅在用户的个人资料处于公开可见状态时才会返回;未认领 handle 的用户以及非公开个人资料会省略该字段。

app object

该安装所属的应用。

app.id string

app.displayName string

应用注册的显示名称，存在时绝不为空。若入队时的数据填充无法解析该应用，则省略此字段。

event.payload 示例：

{  "installation": {    "id": "inst_01k2ja2000e0080000000000b2",    "appId": "app_01k2ja2000e0080000000000a1",    "target": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    },    "repoSelectionMode": "selected",    "repositories": [      {        "id": "repo_01k2ja2000e0080000000000q4",        "name": "rocket",        "owner": {          "slug": "acme",          "id": "ns_01k2ja2000e0080000000000p3",          "type": "team"        }      }    ],    "scopes": [      "repository:contents:read",      "repository:pull_requests:read"    ],    "repositoriesCount": 1,    "createdAt": "2026-08-01T09:30:00Z",    "installedBy": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    }  },  "app": {    "id": "app_01k2ja2000e0080000000000a1",    "displayName": "CI Status Bot"  }}

安装已删除

EVENTinstallation.deleted

负载字段

installation 对象

事件发生时的安装快照。

installation.id string

installation.appId string

已安装应用的标识符；与负载中的 app.id 取值相同。

installation.target 对象

仓库的所有者。

installation.target.slug string

所有者的唯一 URL 友好名称。

installation.target.id string

所属 namespace 的唯一 ID。

installation.target.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

installation.repoSelectionMode string

取值为 all 或 selected。

installation.repositories 数组

当 repository_selection 为 "all" 时为空。最多返回 5,000 条；实际总数请参见 repositories_count。

installation.repositories[].id string

installation.repositories[].name string

installation.repositories[].owner 对象

仓库的所有者。

installation.repositories[].owner.slug string

所有者的唯一 URL 友好名称。

installation.repositories[].owner.id string

所属 namespace 的唯一 ID。

installation.repositories[].owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

installation.scopes 数组

installation.repositoriesCount integer

实际总数；当 repository_selection 为 "all" 时为 0。

installation.createdAt string

RFC 3339 格式的 timestamp。

installation.updatedAt string

RFC 3339 格式的 timestamp。

installation.deletedAt string

RFC 3339 格式的 timestamp。

installation.suspendedAt string

安装处于暂停状态时会设置该字段；处于活跃状态时则不设置。RFC 3339 时间戳。

installation.installedBy 对象

最初安装该应用的用户。

installation.installedBy.id string

installation.installedBy.email string 必填

installation.installedBy.displayName string

便于阅读的显示名称：账户的名与姓各自去除首尾空白后以空格连接，与产品 UI 中呈现的名称完全一致。账户没有名称时省略该字段；绝不会根据电子邮件、id 或其他任何字段合成。若 webhook 负载的操作者无法解析，该字段也可能不存在。

installation.installedBy.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 所对应的身份标识) ，不含 @ 前缀。仅在用户的个人资料处于公开可见状态时才会返回；未认领 handle 的用户以及非公开个人资料会省略该字段。

app object

该安装所属的应用。

app.id string

app.displayName string

应用注册的显示名称，存在时绝不为空。若入队时的数据填充无法解析该应用，则省略此字段。

event.payload 示例：

{  "installation": {    "id": "inst_01k2ja2000e0080000000000b2",    "appId": "app_01k2ja2000e0080000000000a1",    "target": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    },    "repoSelectionMode": "selected",    "repositories": [      {        "id": "repo_01k2ja2000e0080000000000q4",        "name": "rocket",        "owner": {          "slug": "acme",          "id": "ns_01k2ja2000e0080000000000p3",          "type": "team"        }      }    ],    "scopes": [      "repository:contents:read",      "repository:pull_requests:read"    ],    "repositoriesCount": 1,    "createdAt": "2026-08-01T09:30:00Z",    "installedBy": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "jane@acme.dev"    },    "deletedAt": "2026-08-03T08:15:00Z"  },  "app": {    "id": "app_01k2ja2000e0080000000000a1",    "displayName": "CI Status Bot"  }}