Skip to main content

Command Palette

Search for a command to run...

API

Origin API

Origin 是 Cherri Code 的代码托管平台。其公开的 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 当作默认值。文档中标注为不出现或被省略的字段在合约中是可选的，未设置时不会出现在响应体中。

预览版

部分 API 接口以预览版形式发布。这些接口会出现在本参考文档和规范中，但在正式发布前，其结构可能会发生变化。OpenAPI 规范会将其标记为 x-cursor-visibility: PREVIEW。该标记可以出现在操作、参数、schema 或单个字段上，因此即使是稳定的操作，也可能返回预览版字段。处于预览阶段的端点在本参考文档中会带有 预览版 badge。请将预览版字段视为可选字段，不要对其结构形成硬性依赖。

入门

访问 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 身份验证 使用安装访问令牌克隆，而非使用用户登录。

安装

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

/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，而非伪造的重定向，并携带回调所需的全部信息。Cherri Code 不会在缺少此凭据时进行重定向，因此外部回调始终会携带它。

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": "[email protected]",    "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，在到期前刷新，将其视为密码，切勿记录到日志中。

令牌最长在创建后 15 分钟过期，且不会晚于请求它的应用 JWT，因此上文推荐的五分钟 JWT 最多只能签发出有效期五分钟的令牌。请读取 expiresAt，在其过期后签发新令牌，而不要假定某个固定时长：源站令牌的有效期比 GitHub App 安装访问令牌更短，若集成按 GitHub 的周期复用令牌，会在令牌过期后失败。当某个作业需要完整的 15 分钟时，请在签名 JWT 时设置更晚的 exp，参见 CloneKit CI 方案。

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

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

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

若要以该安装所属命名空间的成员身份 (而非应用身份) 执行操作，请签发安装用户令牌。参见代表用户执行操作。

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 到期前签发新的令牌。

Git over HTTPS 有独立的预算计量，与 限额 中的 REST 预算相互独立。计费的 Git 响应会带有相同的 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Used 请求头，其中 X-RateLimit-Resource 为 git 而非 core。超出预算的 Git 请求会返回 429，并附带 Retry-After 和 X-RateLimit-Reset。请读取请求头来控制作业节奏，而不要假定某个具体数值；不计量的请求不会带有限额相关请求头。

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

用户认证的 CLI 请求

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

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

对于非交互式会话，请在 Cherri Code 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读取直接在所有者上持有的授权。读取所有者信任的 SSH 证书颁发机构，以及该所有者是否要求使用证书。
namespace:settings:write更新或插入以及删除所有者上的授权。添加和移除 SSH 证书颁发机构，并设置所有者是否要求使用证书；这些写入操作由 Cherri Code 用户凭据携带。
namespace:user_tokens:write签发安装用户令牌，以安装所属命名空间成员的身份执行操作。令牌本身不能携带此权限范围。请参阅代表用户操作。

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

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

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

安装管理同样不在此表范围内。Add App Installation Repositories 需要 namespace:installations:write，应用无法在安装时请求该权限：它由命名空间管理员在 Cherri Code 用户凭据上持有，且只有与同意该安装时相同类型的凭据才能扩展它。

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

该表涵盖应用在安装时请求的权限范围。要查找单个操作所需的权限范围，请参阅其在 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 点数/分钟
Cherri Code 用户或服务账户600 点数/分钟

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

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

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

响应头

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

请求头描述
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。请勿解析或自行构造。

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

在同一请求序列中 (包括后续请求) ，每次请求都应发送相同的 pageSize。大多数列表端点会将与页面 token 一同发送的 pageSize 应用于该页；若省略 pageSize，则沿用上一页的大小。这些端点的 pageToken 条目中会注明这一点。其余端点的页面 token 所记录的信息各不相同，因此保持 pageSize 不变，即可在所有端点获得一致的页面大小。

错误

错误响应采用 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 条目，因此就失败的调用联系 Cherri Code 时，请提供请求 ID。

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

ID

Resource ID 是带有类型前缀的不透明 string，例如应用 ID 以 app_… 开头，安装 ID 以 i_… 开头。请将其作为完整的 string 进行存储和比较。不要解析 ID，不要从其字符推断含义，也不要依赖其排序顺序。

ID 在其 resource 的整个生命周期内保持不变，而名称和 slug 则可能变化。代码仓库重命名后仍保留原有 ID，因此缓存数据时应以 ID 而非 {ownerSlug}/{repoName} 作为键，并按照代码仓库路径中的说明，通过 ID 引用代码仓库。

代码仓库路径

代码仓库范围内的路径使用 {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 之一。仅存在一个变体；请从该变体中读取身份信息。

Check runs

应用通过 Post Check Run 和 Batch Upsert Check Runs 将 CI 结果以 check suite 和 check run 的形式上报到某个提交，再通过 Checks 端点读回这些结果。本节定义这些端点共用的概念：哪一次尝试为当前尝试、源站如何对写入操作排序并上报，以及 timestamp 和截止时间的行为。

尝试与当前尝试

针对某个提交上报的每个 (actor, key, externalId) 都是一次 suite 尝试，其中每个 (suite, key, externalId) 都是一次 run 尝试。复用同一个 externalId 会就地更新该次尝试；使用新的 externalId 则会开启一次新尝试，并把此前的尝试保留为历史。被取代的尝试仍可通过 获取检查套件 和 获取检查 run 按 id 读取。

在 API 展示某个提交的当前检查的位置，即 List Check Suites For Commit、List Check Runs For Commit，以及 PR 的 CI 状态和必需检查中，源站会通过两步收敛这些尝试：

  1. 每个 (actor, key) 的当前 suite 尝试，是其当前 run (按第二步选出) 携带最新 externalUpdatedAt 的那一次；没有 run 的 suite 则按自身的 createdAt 排序。若相同，则依次按 suite 的 createdAt、id 排序，最新在前。
  2. 在该 suite 尝试内，某个 key 的当前 run 是 externalUpdatedAt 最新的那一次。若相同，则依次按 createdAt、id 排序，最新在前。

List Check Runs For Suite 只对你指定的 suite 应用第二步。只有当某个 run 所属的 suite 是该提交的当前 suite 尝试时，它才是该提交的当前 run。由于第一步是对整个 suite 尝试排序，只要另一次尝试的 externalUpdatedAt 更新，在已被取代的 suite 尝试下提交的 run 就不会出现在该提交的检查中；而一旦它的时间戳成为最新，其 suite 尝试就成为当前尝试，转而隐藏另一次尝试的 run。

已取消的尝试不会取代已通过的尝试。在任一步中，如果某个 key 最新的未取消尝试已通过，则已取消的尝试会排在该 key 的其他尝试之后。当 run 状态为 completed 且结论为 success、neutral 或 skipped 时，该 run 视为已通过。当 suite 尝试的所有当前 run 都已通过时，该 suite 尝试视为已通过；当其当前 run 均为 completed，且至少一个结论为 cancelled、其余均已通过时，该 suite 尝试视为已取消。当请求重新运行已通过的尝试时，externalUpdatedAt 等于或晚于该请求时间的已取消尝试会重新按时间戳排序。较新的已取消 suite 尝试仍会取代未完全通过的较早尝试。

已被请求重新运行的 run，仍会保持其 key 的当前尝试地位，并在所属应用作出响应前显示为待处理：参见 Rerequest Check Run。

写入排序

对于同一 suite 中 externalId 和 key 相同的同一个 run，源站按 checkRun.externalUpdatedAt 以毫秒精度对提交排序。只有当提交的值等于或晚于该 run 已存储的 externalUpdatedAt 时才会生效；若存在尚未完成的重新请求，该基准会提升为 rerequestedAt。值相等时同样生效，因此后提交者胜出，但有两种例外也被视为过时：queued 或 in_progress 的提交不能在相同时间戳上重新打开已 completed 的 run；以及在设置了 rerequestedAt 时，时间戳与存储值完全相同的提交会被忽略。更新的值会生效，包括重新打开已 completed 的 run，但有一种例外：无论时间戳如何，结论为 cancelled 的 completed 提交都不能替换结论为 success、neutral 或 skipped 的 completed run；此类提交会被视为过时。

过时的提交仍会返回成功。响应为 HTTP 200，其中返回的是已存储的 suite 和 run，而非提交的值，且该 run 的 updatedAt 不会变化。每个提交的 run 都会以一对值返回：checkRun 是调用后已存储的 run，outcome 是本次写入对它所做的操作。Post Check Run 在响应顶层返回这对值，与 checkSuite 并列。Batch Upsert Check Runs 在 results[] 中按请求顺序为每个提交的 run 返回一对值，因此批处理中每个元素携带的单个 run 结果，与单次调用内联返回的结果一致。读取 outcome 或各个 results[].outcome，即可了解本次写入的行为：

outcome含义
created该 suite 中不存在与 (externalId, key) 对应的 run；已创建一个。
updated已有的 run 被提交的值替换。
unchanged提交的值 (包括 externalUpdatedAt) 与已存储的 run 相同；未写入任何内容。
ignored_stale该提交因过时被忽略；checkRun 携带的是已存储的 run，而非提交的值。

unchanged 与 ignored_stale 两种提交都不会推进 updatedAt，因此无法据此区分二者，只能依靠 outcome。遇到无法识别的值时，应理解为“响应中是已存储的 run；是否发生写入未知”。在批处理中，源站会对每个 run 分别应用该规则：某个 run 过时不会导致整个批处理失败，results[] 会在该 run 对应的位置携带已存储的 run，并将 outcome 设为 ignored_stale。

在 Batch Upsert Check Runs 中，顶层的 checkRuns[] 已弃用，应改用 results[]。它仍会以相同顺序填充相同的已存储 run，但不携带 outcome；请改为读取 results[]。这仅适用于批处理：在 Post Check Run 中，应读取的顶层字段是 checkRun 和 outcome。

时间戳与截止时间

若某次提交的 externalUpdatedAt、startedAt 或 completedAt 比当前时间超前 60 秒以上，则返回 InvalidArgument (HTTP 400) 。当同一次提交中同时包含两者时，completedAt 不得早于 startedAt。deadlineAt 距当前时间不得超过 24 小时。

只有 in_progress 状态的运行会过期。一旦其 deadlineAt 已过，定期清理任务会以 timed_out 结论将其标记为完成；若该运行尚无 completedAt，则为其设置该值，并清除 deadlineAt，同时投递 repository.check_run.completed。过期处理发生在截止时间之后的若干分钟，而非恰好在截止时刻：清理任务默认约每 30 分钟运行一次，这属于可能调整的运维设置，因此请勿依赖该间隔。queued 状态的运行永不过期，没有 deadlineAt 的运行同样不会过期。completed 的提交会清除截止时间。源站将运行判定为超时时不会改动 externalUpdatedAt，因此后续携带更新的 externalUpdatedAt 的提交仍可作用于已超时的运行。

当前限制

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

实施检查清单

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

端点参考

下载OpenAPI 规范，查看完整的组件架构。该文档将 https://api.cursor.com 声明为服务器，并定义了 bearerAuth HTTP Bearer 安全方案；每个操作都会列出该操作可能返回的响应代码，以及请求和响应示例。每个操作还带有 x-origin-scopes 扩展：scopes 表示该操作所需的作用域，tokenTypes 表示它接受的凭据类型。每个 webhook 负载架构都带有 x-origin-webhook-events 扩展，列出投递该负载的事件；预览版接口则带有 x-cursor-visibility: PREVIEW。路径参数与 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 事件订阅。installation.* 事件始终会投递，且不会出现在此处。

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

创建安装用户 token

POST/v1/origin/app/installations/{installationId}/user_access_tokens
Installation scopenamespace:user_tokens:writeAuthApp JWT

创建一个安装用户 token，以该安装所属命名空间中的一位成员的身份操作。

该安装必须属于已认证应用，且已接受 namespace:user_tokens:write。必须通过 userId 或 userEmail 指定用户，且只能使用其中一个。如果用户不存在、无法唯一确定或不符合使用条件，API 将返回 PermissionDenied (HTTP 403) ，且不会透露具体原因。

该 token 的访问权限仅限于安装和用户共同拥有的权限。如果同时设置了 scopes 和 repositoryIds，安装和用户都必须对列出的每个代码仓库拥有所请求的每项作用域权限，否则请求将返回 PermissionDenied (HTTP 403) 。完整流程请参阅代表用户操作。

路径参数

installationId string 必填

用于限定 token 作用范围的安装唯一标识符。该值从 URL 路径中获取；安装必须属于已认证应用。

请求体

userId string

用户的 user_… ID，由 actor 负载返回。必须设置 userId 或 userEmail，且只能设置其中一个。

userEmail string

用户的账户电子邮件地址。必须恰好匹配一位符合条件的命名空间成员。

scopes array

用于限制 token 权限的作用域字符串。各值不得重复，且必须包含在安装已接受的作用域中。请求 namespace:user_tokens:write 会返回 InvalidArgument (HTTP 400) ；该作用域用于授权签发 token，不能委托给 token。留空或省略则不限制作用域。

repositoryIds array

用于限制 token 访问范围的代码仓库 ID。各值不得重复，安装必须能够访问这些代码仓库，且最多只能指定 50 个。留空或省略则不限制代码仓库。

响应字段

token string

短期安装用户 token。请将其视为机密信息，不要记入日志。

expiresAt string

RFC 3339 格式的过期时间；该 token 的有效期最长为 15 分钟，且不会晚于签发它所用的应用 JWT 过期。
curl --request POST \  --url 'https://api.cursor.com/v1/origin/app/installations/INSTALLATION_ID/user_access_tokens' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "userId": "user_01k2ja2000e0080000000000c3",  "scopes": [    "repository:pull_requests:reviews:write"  ],  "repositoryIds": [    "repo_01k2ja2000e0080000000000q4"  ]}'

响应结构：

{  "token": "YOUR_INSTALLATION_USER_TOKEN",  "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 的不透明游标。第一页时为空。请求后续页面时必须使用相同的过滤条件。后续请求中的 pageSize 仅作用于该页；省略此参数则沿用上一页的页面大小。

filter string

可选的子串筛选条件，不区分大小写，作用于代码仓库名称和所有者命名空间。含单个斜杠的 owner/repo 值会将两部分分别与对应字段匹配。开头和结尾的空白字符将被忽略；值为空时不应用任何筛选。

响应字段

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}
Scopenamespace:apps: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 事件订阅。installation.* 事件始终会投递，且不会出现在此处。

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

更新应用

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。传入空字符串将禁用 webhook 投递，并取消该应用待投递的记录。

events object

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

events.events 数组

该应用全新的完整 webhook 事件订阅集合。传入空列表将清除代码仓库订阅；installation.* 事件始终会投递，无法在此列出。

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 事件订阅。installation.* 事件始终会投递，不会在此列出。

createdAt string

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

updatedAt string

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

installationRedirectUris 数组

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

namespaceSlug string

拥有该 app 的 namespace 的 slug。

description string

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

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) 。

发起请求时，namespace 所有者必须具备向 Origin 写入的资格，这与创建代码仓库的要求相同。个人所有者必须使用 Pro、Pro Student、Pro+、Ultra 或 Start 方案。团队所有者必须拥有有效的付费团队方案，不得启用隐私模式 (旧版) ，且未被团队管理员关闭 Origin。若所有者不符合资格，则返回 FailedPrecondition (HTTP 400) 。Origin 读取的是 namespace 所有者的资格，而非调用方用户的资格。

路径参数

namespaceSlug string 必填

将拥有该应用的命名空间的 slug。

请求体

displayName string 必填

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

publicKey string 必填

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

webhookUrl string

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

events array

Webhook 事件订阅，以 Events 中的事件 slug 表示。未知事件类型会被拒绝。空列表表示不订阅任何事件，因此应用只会收到始终会投递且无法在此列出的 installation.* 事件。

description string

应用的简短描述。

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 事件订阅。installation.* 事件始终都会投递，因此不会出现在此处。

createdAt string

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

updatedAt string

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

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

添加应用安装的仓库

POST/v1/origin/namespaces/{namespaceSlug}/installations/{installationId}/repos
Scopenamespace:installations:writeAuthUser access token

将仓库添加到某个安装的代码仓库选择范围中，并返回更新后的安装。该写入操作为增量操作：列出的仓库会并入当前选择；如果请求中列出的仓库已全部被授予，则请求成功但不作任何更改；安装的作用域始终不会改变。

列出的每个代码仓库都必须属于目标命名空间，否则请求将返回 FailedPrecondition (HTTP 400) 且不会授予任何权限。以下情况同样返回该错误：安装已覆盖该命名空间中的所有仓库 (repoSelectionMode 为 all)、安装处于挂起状态，以及安装早于支持按安装设置作用域的版本。若安装不存在或属于其他命名空间，则返回 404；当该应用从未在此命名空间中安装过时，错误消息会指明需要打开的授权页面，因为此端点无法执行首次安装。

调用方必须使用拥有该命名空间安装管理权限的 Cherri Code 用户凭据。应用令牌、安装令牌和服务账户无法更改安装的仓库。

路径参数

namespaceSlug string 必填

该安装所属命名空间的 slug。

installationId string 必填

安装标识符。

请求体

repoIds array 必填

要添加到安装选择中的存储库 ID。至少需要一个；值会去重，已在选择中的存储库会保持不变。列出的每个存储库必须属于该命名空间，否则请求将失败且不会授予任何权限。

响应字段

id string

安装标识符，应用会将其存储并用于签发安装访问令牌。

appId string

已安装应用的标识符。

target object

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

target.slug string

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

target.id string

源站所有者标识符。

target.type string

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

createdAt string

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

updatedAt string

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

repoSelectionMode string

代码仓库授权模式；精确为全部或已选。

scopes 数组

已批准用于安装的作用域。

installedBy object

最初安装该应用的用户，而非最近一次重新同意 (re‑consent) 的操作者。仅供输出。当无法再读取该用户记录时，字段将缺失。

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 POST \  --url 'https://api.cursor.com/v1/origin/namespaces/NAMESPACE_SLUG/installations/INSTALLATION_ID/repos' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "repoIds": [    "repo_01k2ja2000e0080000000000q4",    "repo_01k2ja2000e0080000000000q5"  ]}'

响应结构：

{  "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",    "repository:metadata:read"  ]}

代码仓库

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

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

列出命名空间

GET/v1/origin/namespaces
AuthUser access token

列出你可在其中列出仓库的命名空间，按 slug 排序。

候选范围包括你所在团队的命名空间、你的个人命名空间，以及包含已授权给你的仓库的命名空间。仅返回你拥有 namespace:repositories:read 权限的命名空间，因此每个结果都可作为 列出仓库 的有效 ownerSlug。

调用方必须使用 Cherri Code 用户凭据；此调用本身无需任何作用域。应用 token、安装令牌和服务账户调用时会收到 PermissionDenied (HTTP 403) 。

查询参数

pageSize integer

返回的命名空间数量上限。未设置或为 0 时，默认值为 30。超过 100 的值按 100 处理。

pageToken string

上一次响应中 next_page_token 返回的不透明游标。请求首页时留空。后续请求中的 pageSize 仅作用于该页；省略则沿用上一页的分页大小。

响应字段

namespaces array

你可在其中列出仓库的命名空间，按 slug 排序。

namespaces[].namespace object

该命名空间的所有者引用。

namespaces[].namespace.slug string

用于 URL 的所有者 slug。可在调用 列出仓库 时将其作为 ownerSlug 传入。

namespaces[].namespace.id string

Origin 所有者标识符。

namespaces[].namespace.type string

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

namespaces[].viewerCanCreateRepositories boolean

你在此命名空间中执行 创建代码仓库 时，能否通过授权以及所有者的套餐和设置检查。

nextPageToken string

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

响应结构：

{  "namespaces": [    {      "namespace": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      },      "viewerCanCreateRepositories": true    },    {      "namespace": {        "slug": "jane",        "id": "ns_01k2ja2000e0080000000000p4",        "type": "user"      },      "viewerCanCreateRepositories": false    }  ]}

列出仓库

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

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

路径参数

ownerSlug string 必填

父级所有者实体的 slug。

查询参数

pageSize integer

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

pageToken string

来自先前响应的 next_page_token 的不透明游标。第一页为空。后续请求中的 pageSize 作用于所请求的该页；省略则沿用上一页的页面大小。

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 的不透明游标。第一页为空。该值编码了续取位置。后续请求中的 pageSize 仅作用于该页；若省略，则沿用上一页的页面大小。

响应字段

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；请跟随重定向获取数据。归档文件包含一个名为 {ownerSlug}-{repoName}-{shortSha}/ 的顶层目录，其中 shortSha 是解析后提交的前 7 个十六进制字符，与 GitHub 的 tarball 端点布局一致。空代码仓库返回 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 匹配，也可选择与 run key 匹配。name 仅用于显示，不参与匹配。
  • 请在多次尝试中保持 key 值稳定且易于用户理解，因为必需检查的配置以它们为键。
  • 重用 externalId 可更新一次尝试，这会丢弃该尝试之前的结果；重试时请使用新的 externalId，以便将较早的尝试保留为历史记录。
  • 使用 checkRun.output 提供用户可读的结果：
    • title：简短的结果标题，最多 255 个字符。
    • summary：主要的 Markdown 摘要，最多 65,535 个 UTF-8 字节。
    • text：扩展的 Markdown 详细信息，最多 65,535 个 UTF-8 字节。
  • 使用 detailsUrl 链接到提供方的外部结果页面。

Check runs 定义了哪次尝试为当前尝试、externalUpdatedAt 如何为写入操作排序、outcome 报告哪些内容，以及这些端点共用的时间戳与截止时间规则。

创建检查运行

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 用于确定同一运行标识的更新顺序；过期重试不会覆盖较新的状态，且 cancelled 状态的完成结果不能替换已存储的通过结果；参见写入顺序。被忽略的过期提交和重复已存储值的提交，都会返回 200 以及已存储的套件和运行，因此应读取 outcome，以区分 ignored_stale 和 unchanged 与 created 和 updated。这两种情况下 updatedAt 都不会变化，因此无法据此区分。

在同一个 suite 内，某个运行 key 的当前尝试是 externalUpdatedAt 最新的那次运行；若相同，则依次按 createdAt、id 排序，最新者优先。针对某个提交上报的每个 (actor, key, externalId) 即为一次 suite 尝试；每个 (actor, key) 的当前尝试是其运行带有最新 externalUpdatedAt 的那次，而没有任何运行的 suite 则按其自身的 createdAt 排序。只有当某次运行所属的 suite 是该提交的当前尝试时，该运行才是该提交的当前运行；因此，只要同一 suite 的另一次尝试有更新的活动，以较早的 suite externalId 提交的运行就不会出现在以提交为作用域的列表中。在这两个层级上，已取消的尝试都不会取代已通过的尝试，具体规则参见尝试与当前尝试。被取代的尝试仍可按 id 读取。

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

当某个仍处于 in_progress 的运行超过截止时间时，Origin 会自行以 timed_out 结论完成该运行，若该运行尚无 completedAt 则为其设置该值，并发送 repository.check_run.completed。过期处理作为周期性扫描运行，而不是基于每个运行的定时器，因此过期会在截止时间之后数分钟才生效，而非恰好在截止时间生效。该扫描默认约每 30 分钟运行一次，这是一项可能变更的运维设置。处于 queued 状态的运行永不过期，未包含 deadlineAt 的运行也不会过期。在截止时间之前自行完成该运行即可清除其截止状态。Origin 在将运行判定为超时时不会更改该运行的 externalUpdatedAt，因此来自你的提供者的后续完成仍然可以覆盖 timed_out 结论。

路径参数

ownerSlug 字符串 必填

所属实体的唯一标识符。

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 必填

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

checkRun.status string 必填

可设置的值：CHECK_RUN_LIFECYCLE_STATUS_UNSPECIFIED、queued、in_progress、completed。模式还列出了 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

检查运行开始时。如果某个值比当前时间晚超过 60 秒，则会返回 InvalidArgument (HTTP 400)。

checkRun.completedAt string

检查运行的完成时间。如果该值晚于当前时间超过 60 秒，将返回 InvalidArgument (HTTP 400)；如果与 startedAt 一并提交且早于 startedAt，同样会返回该错误。

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

源所有者标识符。

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

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

checkSuite.actor.user.displayName string

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

checkSuite.actor.user.handle string

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

checkSuite.actor.app 对象

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

checkSuite.actor.app.id string

应用的公开标识符。

checkSuite.actor.app.displayName string

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

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

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

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

产生该运行的公共主体。始终为所属检查套件的 actor。

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

应用已注册的显示名称。当应用无法解析，或该应用是 Cherri Code 的第一方托管主体时，此项省略。

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 就会存在，并随其一同清除。

outcome string

此次调用对 checkRun 执行的操作。允许的值：created、updated、unchanged、ignored_stale。因数据过时而被忽略的提交，以及重复已存储值的提交，都会返回已存储的运行；此字段是区分二者的唯一方式。
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": "[email protected]"      }    }  },  "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": "[email protected]"      }    },    "output": {      "title": "Unit tests",      "summary": "128 tests passed.",      "text": "All suites green."    }  },  "outcome": "created"}

批量更新或插入检查运行

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

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

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

Origin 会分别对每个运行应用 externalUpdatedAt 排序规则。被判为过时而被忽略的运行不会导致批处理失败：响应会在其位置返回已存储的运行，且 results[].outcome 会按请求顺序报告每个运行的裁决。

路径参数

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

检查运行开始的时间。未来超过 60 秒的值会返回 InvalidArgument (HTTP 400) 。

checkRuns[0].completedAt string

检查运行完成的时间。值超过未来 60 秒会返回 InvalidArgument (HTTP 400) ；如果与 startedAt 一并提交且早于 startedAt 的值也会返回该错误。

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 更新被重新请求的运行，从而就地刷新它。在新的发布到达之前，被重新请求的运行在该提交的最新检查状态中会显示为待处理，因此必需的检查会阻止合并，拉取请求会显示该运行正在等待重新运行；声明可重新请求但不予响应会使该检查陷入搁置。发布时 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

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

checkSuite.actor.serviceAccount 对象

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

checkSuite.actor.serviceAccount.id string

服务帐户的公共标识符。

checkRuns 数组

已弃用：请改为读取 results[].checkRun。该字段仍会按请求顺序填充。

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

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 对象

发起此次运行的公共参与者。始终是所属检查套件的 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

应用的注册显示名称。当应用无法解析，或在 Cherri Code 的第一方托管 actor 上时省略。

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 对象

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

results 数组

每个已提交的运行对应一个结果，按请求顺序返回。

results[].checkRun 对象

此次调用后存储的检查运行：当 outcome 为 created 或 updated 时，使用已提交的值；否则保持该运行原有的值。字段与 checkRuns[] 相同。

results[].outcome string

此次调用对 results[].checkRun 所做的操作。允许的值：created、updated、unchanged、ignored_stale。因过时而被忽略的运行与返回已存储值的重复运行都会返回已存储的运行，因此只能通过此字段将它们区分开来。
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": "[email protected]"      }    }  },  "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": "[email protected]"        }      },      "output": {        "title": "Unit tests",        "summary": "128 tests passed.",        "text": "All suites green."      }    }  ],  "results": [    {      "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": "[email protected]"          }        },        "output": {          "title": "Unit tests",          "summary": "128 tests passed.",          "text": "All suites green."        }      },      "outcome": "created"    }  ]}

获取检查运行

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 运行是指已完成且已请求重新运行但所属应用尚未响应的运行：应将其视为待处理，并按 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。

actor.user 对象

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

actor.user.id string

用户的公开标识符。

actor.user.email string

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

actor.user.displayName string

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

actor.user.handle string

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

actor.app 对象

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

actor.app.id string

应用的公开标识符。

actor.app.displayName string

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

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 相同的 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": "[email protected]"    }  },  "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 会为后续整个序列固定范围。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

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

checkRunId string 必填

服务器分配的 check run ID。

查询参数

pageSize 整数

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

pageToken string

来自上一次响应的 nextPageToken 的不透明游标。第一页可省略。后续请求中的 pageSize 仅对该页生效；省略则沿用上一页的分页大小。

响应字段

annotations array

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

annotations[].id string

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

annotations[].checkRunId string

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

annotations[].annotationLevel string

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

annotations[].message string

注释消息。可能包含 Markdown。

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 必填

注解消息。可包含 Markdown。不能为空。最大 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

注释信息。可能包含 Markdown。

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 的当前尝试，并且必须位于开放 PR 的当前 head 上。否则将返回 FailedPrecondition (HTTP 400) 。

每次运行同时只能有一个未完成的重新请求。当 rerequestedAt 已设置时再次请求会返回 AlreadyExists (HTTP 409 Conflict) ；在拥有该运行的应用作出响应后，该运行将再次变为可重新请求。任何持有 repository:contents:write 权限的主体都可以重新请求任何可重新请求的运行，无论是哪一个应用上报的。若 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。

actor.user 对象

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

actor.user.id string

用户的公开标识符。

actor.user.email string

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

actor.user.displayName string

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

actor.user.handle string

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

actor.app 对象

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

actor.app.id string

应用的公开标识符。

actor.app.displayName string

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

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 对象

请求重新运行的主体 (Principal) ，携带与 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": "[email protected]"    }  }}

获取检查套件

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

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

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": "[email protected]"    }  }}

列出套件的检查运行

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

列出某个 suite 当前的检查运行。若在该 suite 中某个 run key 被报告多次，则仅返回该 key 的最新一次尝试；被取代的尝试会被省略。Post Check Run 定义了哪次尝试是最新的。已重新请求的运行仍会保留在列表中并显示为待处理，其 status 为 rerequested 且 rerequestedAt 已设置，其被取代的 conclusion 与时间信息保持不变，直到拥有该运行的应用作出响应。可通过 Get Check Run 使用被取代尝试自身的 id 来读取该尝试。支持分页。

路径参数

ownerSlug 字符串 必填

所属实体的唯一 slug。

repoName string 必填

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

checkSuiteId 字符串 必填

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

查询参数

pageSize 整数

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

pageToken string

来自先前响应的 next_page_token 的不透明游标。第一页时为空。对该套件范围内最后看到的 check-run id 进行编码。后续请求中的 pageSize 适用于该页；省略则沿用先前的每页大小。

响应字段

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

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

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 对象

发起该运行的公共主体。始终为所属检查套件的 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

应用已注册的显示名称。当应用无法解析时，以及对于 Cherri Code 的第一方托管 actor，此字段将被省略。

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 对象

请求重新运行的主体 (principal) ，携带与 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": "[email protected]"        }      },      "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

列出某个提交在所有 suite 中当前的检查运行：仅包含每个 suite 最新一次尝试中的运行，且在每个 suite 内，每个运行键只保留最新一次尝试。 已被取代的尝试将被省略；提交检查运行 定义哪次尝试是最新的。 被重新请求的运行会保留在列表中并显示为待处理：其 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 的不透明游标。第一页时为空。它编码了限定在此提交及下述筛选条件范围内的最后返回的检查运行 ID；若在不同筛选条件下重用同一 token，将返回 InvalidArgument (HTTP 400)。后续请求中的 pageSize 仅作用于该页；省略则沿用上一页的页面大小。

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

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

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 对象

生成该运行的公共主体。始终为所属检查套件的 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

应用已注册的显示名称。当应用无法解析或为 Cherri Code 第一方托管的 actor 时省略。

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 相同的主体变体。只要设置了 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": "[email protected]"        }      },      "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。后续请求中的 pageSize 将应用于该页；省略此参数则沿用之前的页面大小。

响应字段

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

应用已注册的显示名称。若应用无法解析，或在 Cherri Code 的第一方托管 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": "[email protected]"        }      }    }  ]}

提交和内容

提交将 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

来自先前响应中 nextPageToken 的不透明游标。第一页时为空。该游标编码了起始引用、遍历位置和电子邮件筛选条件；因此在提供 token 时，sha、pageSize、authorEmails 和 committerEmails 会被忽略。经过筛选的页面可能包含少于 pageSize 个提交，甚至不包含任何提交，但 nextPageToken 仍会被设置。请持续翻页，直到该值为空。

authorEmails 数组

可选的 Git 作者电子邮件筛选条件。去除首尾空白字符后，不区分大小写地匹配列出的任意电子邮件地址。忽略空白条目和重复项。最多可指定 100 个不同的电子邮件地址；留空则不筛选。这里指的是 Git 作者的电子邮件地址，而非 Origin 操作主体的 ID。每页最多扫描 1,000 个提交以查找匹配项。

committerEmails 数组

可选的 Git 提交者电子邮件筛选条件。与 authorEmails 采用相同的规范化规则，且同样最多支持 100 个电子邮件；留空表示不筛选。同时设置两个筛选条件时，提交须同时匹配两个列表。每页最多扫描 1,000 个提交来查找匹配项。

响应字段

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": "[email protected]",          "date": "2026-08-01T09:30:00Z"        },        "committer": {          "name": "Jane Doe",          "email": "[email protected]",          "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 string 必填

所有者实体的唯一 slug。

repoName string 必填

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

sha string 必填

要获取的提交的 SHA、分支、标签或符号引用 (例如 HEAD) 。缩写 SHA 的解析方式与 获取 Git 提交 中相同。

响应字段

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": "[email protected]",      "date": "2026-08-01T09:30:00Z"    },    "committer": {      "name": "Jane Doe",      "email": "[email protected]",      "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 必须与该令牌匹配。每个文件包含 filename、status、additions、deletions、changes、patch，以及在重命名或复制时的 previousFilename。二进制文件的 patch 为空。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

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

sha string 必填

要列出文件的提交的 SHA、分支、标签或符号引用 (例如 HEAD) 。缩写 SHA 的解析方式与 获取 Git 提交 中相同。

查询参数

pageSize integer

返回的最大变更文件数。未设置或为 0 时默认为 30。超过 100 的值会被限制为 100。

pageToken string

来自先前响应的 next_page_token 的不透明游标。第一页为空。该令牌固定了解析的提交和文件游标，因此后续请求中的 sha 必须与该令牌匹配。后续请求中的 pageSize 仅作用于该页；省略则沿用先前的页面大小。

响应字段

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 值必须与之匹配。
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": "[email protected]",        "date": "2026-08-01T09:30:00Z"      },      "committer": {        "name": "Jane Doe",        "email": "[email protected]",        "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": "[email protected]",        "date": "2026-08-01T09:30:00Z"      },      "committer": {        "name": "Jane Doe",        "email": "[email protected]",        "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": "[email protected]",        "date": "2026-08-01T09:30:00Z"      },      "committer": {        "name": "Jane Doe",        "email": "[email protected]",        "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 必须与该令牌匹配。Origin 会在每一页重新解析比较；如果自令牌发放以来其提交已发生变动，请求将返回 InvalidArgument (HTTP 400) ，且必须从第一页重新开始列出。后续请求中的 pageSize 仅作用于该页；省略该参数则沿用之前的页面大小。

响应字段

files 数组

分页返回修改的文件，包括文件名、状态、行数、补丁，以及重命名或复制文件的 previousFilename (原文件名) 。二进制补丁为空。

files[].filename string

修改的文件的路径。

files[].status string

变更状态：新增、删除、修改、重命名或复制。

files[].additions integer

为该文件添加的行数。

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。空白字符同样有效，会按原样参与搜索。当 literal 为 false 时，不区分大小写的匹配通过在模式开头添加 (?i) 实现 (例如 (?i)launch) ，全词匹配则通过在两侧添加 \b 实现 (例如 \blaunch\b) 。空模式将返回 InvalidArgument (HTTP 400) 。UTF-8 最大长度：4096 字节。

literal boolean

将 query 作为精确文本搜索，而非正则表达式。

caseInsensitive boolean

匹配时将大小写视为等同。仅在 literal 为 true 时应用。正则表达式搜索会忽略此选项；请在 query 中以 (?i) 开头。

wholeWord boolean

仅匹配完整单词。仅在 literal 为 true 时生效。正则表达式搜索时会被忽略；应在模式两侧添加 \b。

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。

除了分支和标签，获取 Git 引用 还可读取 PR 在 pull/{pullNumber}/merge (会被规范化为 refs/pull/{pullNumber}/merge) 处的合并预览：即把该 PR 当前 head 合并到其 base 分支在上次刷新时的 tip 所生成的提交。源站会在 PR 创建、head 被推送、变更目标分支以及被重新打开时刷新该预览；刷新发生在对应的 pull_request.* webhook 事件发布之前，且受限于有限的时间预算。若刷新未能及时完成，则沿用此前的引用，事件仍会照常发布。源站不会因 base 分支自行推进而刷新该预览，并且在合并存在冲突时会删除该引用，因此对一个开启中的 PR 返回 404 意味着存在冲突或预览尚未准备好。每个 PR 版本还会在 version.potentialMergeCommit 中给出各自的测试合并结果，可通过其 state 区分上述两种情况；参见 PR。PR 的 mergeCommitSha 则是另一个提交，仅在合并完成后才会设置。

获取 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 至少需包含 5 个十六进制字符，且仅在提交对象范围内解析；若没有任何提交匹配该缩写，或匹配的提交不止一个，则解析失败。

响应字段

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": "[email protected]",    "date": "2026-08-01T09:30:00Z"  },  "committer": {    "name": "Jane Doe",    "email": "[email protected]",    "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": "[email protected]"  },  "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。

pull/<number>/merge 是 PR 的合并预览：一个将其当前 head 合并到上次刷新时其 base 分支最新提交而产生的提交。它与 PR 的 mergeCommitSha 并非同一个提交，后者仅在 PR 合并后才会设置。PR 的 version.potentialMergeCommit 会报告每个版本的测试合并结果：当某个版本是最新版本且其 state 为 prepared 时，其 sha 就是此引用指向的提交。

源站会在创建 PR、推送其 head、变更其目标分支以及重新打开 PR 时刷新该预览，刷新发生在对应的 pull_request.* webhook 事件发布之前，并在有限的时间预算内完成。若刷新未能及时完成，则保留此前的引用，事件仍会照常发布。源站不会仅因 base 分支有新提交而刷新它；当合并存在冲突时会删除该引用，因此对一个 open 状态的 PR 返回 404 意味着合并存在冲突，或预览尚未准备好。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

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

ref string 必填

Git 引用名称。通常为 heads/<branch> 或 tags/<tag>；可接受前导 refs/，并会将其规范化。也接受符号引用 HEAD (返回为 ref: "HEAD"，并附带最新提交) ，以及用于 PR 合并预览的 pull/<number>/merge。按完整引用名称精确匹配。

响应字段

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 引用

DELETE/v1/origin/repos/{ownerSlug}/{repoName}/git/refs/{ref}
Scoperepository:contents:writeAuthInstallation tokenUser access token

删除分支引用。响应体为空。

仅可删除分支引用。不存在的分支将返回 404。代码仓库的默认分支、受删除规则保护的分支，以及内容从其他托管服务镜像而来的代码仓库，均会返回 FailedPrecondition (HTTP 400)。以被删除分支为 head 的 PR 将被关闭，与推送删除后的行为一致。若分支的 tip 在删除请求进行中发生变化，则会以 FailedPrecondition (HTTP 400) 或 Aborted (HTTP 409 Conflict) 失败；可重试以删除新的 tip。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

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

ref string 必填

要删除的分支引用，格式为 refs/heads/<branch> 或 heads/<branch>。

响应字段

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

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

响应：

204 No Content

列出匹配的 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": "[email protected]",    "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

列出在某个代码仓库上直接获得权限的用户、群组及所属团队群组。不包含从该代码仓库所有者继承的权限。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

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

查询参数

pageSize 整数

返回的最大授权数。未设置或为 0 时默认值为 30；大于 100 的值将被限制为 100。

pageToken string

来自上一次响应的 next_page_token 的不透明游标。第一页时为空。后续请求中的 pageSize 作用于该页；若省略该参数，则沿用上一页的页面大小。

响应字段

grants 数组

直接授予该代码仓库的权限，先按 principal 类型 (群组、所属团队管理员、所属团队成员、用户) 排序，再按 id 排序。若某个 principal 已无法解析为活跃用户、群组或所属团队，则会被略过，因此单页返回的授予记录可能少于 pageSize 条。

grants[].user 对象

用户主体。user、group 或 teamGroup 中恰有一个存在。

grants[].user.id string

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

grants[].user.email string

用户的电子邮件地址。

grants[].user.displayName string

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

grants[].user.handle string

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

grants[].group 对象

Cherri Code 群组 principal：所有者团队拥有的群组，或该团队所属组织中的群组。

grants[].group.id string

群组的公开标识符，以 grp_ 为前缀。

grants[].teamGroup 对象

所属团队的内置组之一，直接授予该仓库，区别于从所有者继承的组。

grants[].teamGroup.kind string

该授权所属的内置组。可选值：members、admins。

grants[].permission string

主体在仓库上拥有的权限。允许的值：read、write、admin、custom。custom 表示自定义策略，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": "[email protected]"      },      "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

设置用户、群组或所属团队群组在某个仓库上直接拥有的权限，替换此前直接授予该主体的任何权限。重复授予该主体已拥有的权限会成功但不产生变更。用户必须是该仓库所有者所属团队或组织的活跃成员。群组必须是所有者团队拥有的群组，或该团队所属组织中的活跃群组；否则请求将返回 FailedPrecondition (HTTP 400)。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

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

请求体

user object

用户主体。user、group 和 teamGroup 中有且仅有一个存在。

user.id string

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

user.email string

用户的电子邮件地址。

user.displayName string

用户的显示名称：由账户的名和姓以空格连接而成，与产品中呈现的名称一致。若账户未设置名称，则省略该字段。

user.handle string

用户已认领的配置文件 handle，不含 @ 前缀。仅当该配置文件公开可见时才会返回，否则将被省略。

group 对象

Cherri Code 群组 principal：由所有者所属团队拥有的群组，或该团队所属组织中的群组。

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 对象

Cherri Code 群组主体：所有者所属团队拥有的群组，或该团队所在组织中的群组。

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": "[email protected]"  },  "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

Cherri Code 群组 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

列出已获准访问某个所有者的对象：用户、群组，以及该所有者所属团队内置的管理员和成员群组。每项授权包含其在该所有者名下所有仓库上授予的权限。针对单个仓库的授权不包含在内；请使用 List Repository Grants 查看这些授权。

路径参数

ownerSlug string 必填

要列出其授权的所有者的 Slug。

查询参数

pageSize integer

返回的最大授权数量。未设置或为 0 时默认值为 30。超过 100 的值会被限制为 100。

pageToken string

取自上一次响应中 next_page_token 的不透明游标。请求第一页时留空。后续请求中的 pageSize 仅作用于所请求的页面；省略该参数则沿用上一页的每页数量。

响应字段

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 对象

Cherri Code 群组主体：由所有者所属团队拥有的群组，或该团队所在组织中的群组。

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": "[email protected]"      },      "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 对象

Cherri Code 群组 principal：由该 owner 所属团队拥有的群组，或该团队所在组织中的群组。

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 object

用户 principal。user、group 和 teamGroup 中有且仅有一个存在。

user.id string

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

user.email string

用户的电子邮件地址。

user.displayName string

用户的显示名称：由账户的名和姓以空格连接而成，与产品中显示的名称一致。若账户未设置姓名，则省略该字段。

user.handle string

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

group 对象

Cherri Code 群组主体：所有者团队拥有的群组，或该团队所在组织中的群组。

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": "[email protected]"  },  "permission": "PERMISSION_WRITE"}

删除 Namespace 授权

DELETE/v1/origin/owners/{ownerSlug}/grants
Scopenamespace:settings:writeAuthInstallation tokenUser access token

移除用户、群组或所属团队群组直接在某个所有者上持有的权限。代码仓库授权不受影响。若移除的权限 principal 并未直接持有，请求仍会成功，但不产生任何变更；若移除后该所有者将不再有 admin，则返回 FailedPrecondition (HTTP 400) 。响应体为空。

路径参数

ownerSlug string 必填

所有者 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

Cherri Code 群组 principal：由所有者的团队拥有的群组，或该团队所在组织中的群组。

group.id string

群组的公开标识符，前缀为 grp_。

teamGroup object

所属团队的内置群组之一：即团队对该所有者的默认访问权限。

teamGroup.kind string

持有该授权的内置群组。允许的值：members、admins。

响应字段

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

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 的不透明游标。获取第一页时省略。后续请求中的 pageSize 仅作用于该页；省略则沿用上一页的页面大小。

响应字段

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 视为不透明的 源站 引用 string；它们可能是简短的分支名称，也可能是完全限定的 refs/heads/… 值。

version 是该 PR 最新的编号修订版本。当 head 被推送、PR 被重新指向另一个 base，或 PR 在关闭期间 head 发生移动、随后被重新打开时，源站 会记录一个新版本，每个版本都有各自的 headSha、baseSha 和 diff 统计信息。若重新打开时记录了新版本，则会发送 pull_request.head_ref.pushed，与推送时发送的事件相同。base 分支自行推进不会记录任何内容，因此 version.baseSha (以及与其镜像的 base.sha) 是记录该版本时解析出的 base tip，在记录下一个版本之前，可能落后于该分支的当前 tip。使用 Get Git Ref 读取分支的当前 tip。

mergeCommitSha 是合并写入 base 分支的提交：合并后会设置，合并前未设置。合并前的预览是 pull/{pullNumber}/merge 引用，是另一个提交；参见 Git data。

version.potentialMergeCommit 报告 源站 对该版本进行测试合并的结果：状态为 prepared、遇到 merge_conflict，或仍为 unknown；准备完成后，还会提供合并提交的 sha 及其所基于的 baseSha。该字段仅描述对应版本，因此 PR 合并后仍会继续报告它。pull_request.* webhook 负载会携带事件发生时的该值。事件只会在一定的时间预算内等待准备完成，因此事件中可能显示 unknown，而稍后调用 Get Pull Request 时显示 prepared；此时请重新读取该 PR，或等待下一个事件。

评审 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 的不透明游标。首页请省略该参数。后续请求中的 pageSize 仅作用于当前请求的页；省略则沿用上一页的每页大小。

author string

可选的作者筛选条件。传入公开主体 ID，该 ID 必须与此端点在 pullRequests[].author.user.id、pullRequests[].author.app.id 或 pullRequests[].author.serviceAccount.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) 。

headSha string

可选的头部提交筛选条件：拉取请求头部提交的完整 40 位或 64 位十六进制 SHA (不区分大小写) 。只要某个已记录版本包含该头部提交 (当前版本或已被取代的版本) ，就会选中该拉取请求，因此请比较每个结果中的 head.sha，以区分二者。其他筛选条件仍然适用，state 默认为 open，因此请传入 state=all，以获取已合并和已关闭的拉取请求。格式错误、缩写或未知的 SHA 均不会匹配任何内容。

stackId string

可选的堆栈筛选：堆栈 ID 可使用 pullRequests[].stack.id 返回的值。仅返回该堆栈的成员，并按请求的排序顺序而非堆栈顺序排列，因此需根据每个成员的 stack.parentPullRequest 重建堆栈。state 仍默认为 open，这会排除已合并的成员；若要获取整个堆栈，请传入 state=all。格式正确但不对应本仓库中任何堆栈的 ID 将返回空列表，任何其他值均会返回 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

拉取请求标题。

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 string

该变更最新版本中此端的顶端提交 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 string

应用已注册的显示名称。当应用无法解析时，或对于 Cherri Code 的第一方托管主体，将省略此字段。

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。此字段在拉取请求合并后设置，合并前不存在。合并前的预览是另一个提交，可通过 pull/<number>/merge 引用使用获取 Git 引用读取。

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[].stack 对象

分支栈归属：此拉取请求所属的一系列相互依赖的拉取请求，每个请求都叠加在其所依赖的请求之上。若拉取请求不属于任何分支栈，则不返回此字段。

pullRequests[].stack.id string

分支栈中所有成员共享的稳定标识符。将其作为 stackId 传入 列出拉取请求 以读取其他成员。

pullRequests[].stack.parentPullRequest 对象

此拉取请求所依赖的父拉取请求。在堆栈根节点上不存在此项。父拉取请求合并后，仍会保持引用，直到子拉取请求更改目标分支或更换父项。

pullRequests[].stack.parentPullRequest.id string

父级拉取请求的稳定源标识符。

pullRequests[].stack.parentPullRequest.number string

父拉取请求的仓库本地编号，以 JSON 字符串编码。

pullRequests[].stack.parentPullRequest.repository 对象

父级所属的代码仓库，包含与检查运行的 repository 相同的 id、name 和 owner 字段。分支栈不会跨越代码仓库，因此这始终是该拉取请求自身的代码仓库。

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 时间戳。

pullRequests[].version.potentialMergeCommit 对象

此版本在 Origin 中的测试合并、将其 headSha 合并到基础分支最新提交上所生成的提交，以及该测试合并的准备进度。每个版本都有此字段。此字段仅描述当前版本，即使拉取请求已合并，仍可读取；该提交与 mergeCommitSha 不同。对于堆叠式拉取请求，基础分支是父拉取请求的分支，因此测试合并仅涵盖此拉取请求在其之上的更改。

pullRequests[].version.potentialMergeCommit.state string

测试合并的准备进度。允许的值：unknown、prepared、merge_conflict。unknown 表示测试合并尚未准备好：该版本仍在等待准备，或准备过程已超时或失败。每个新版本的初始状态都是 unknown，因此不会沿用其他版本的提交。prepared 表示测试合并已生成，sha 和 baseSha 用于描述该合并。merge_conflict 表示将 headSha 合并到基础分支的最新提交时发生冲突，因此没有测试合并；这是获取拉取请求的可合并性报告的 merge_conflict 阻塞状态。重新打开拉取请求会再次准备该版本。将无法识别的值视为 unknown。

pullRequests[].version.potentialMergeCommit.sha string

双亲测试合并提交的 SHA：其第一个父提交是此对象的 baseSha，第二个父提交是该版本的 headSha。仅当 state 为 prepared 时存在。此版本为最新版本时，pull/{pullNumber}/merge 引用指向该提交。此后仍可通过 获取提交 按 SHA 读取该提交，但无法通过 Git 按 SHA 获取。

pullRequests[].version.potentialMergeCommit.baseSha string

构建测试合并时所基于的基础分支末端提交。仅当 state 为 prepared 时才会返回。它可能比 pullRequests[].version.baseSha 更新；如果基础分支只是向前推进，Origin 不会刷新该值。

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": "add-telemetry-schema",        "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"      },      "author": {        "user": {          "id": "user_01k2ja2000e0080000000000c3",          "email": "[email protected]"        }      },      "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"        }      ],      "stack": {        "id": "stk_01k2ja2000e0080000000000s1",        "parentPullRequest": {          "id": "pr_01k2ja2000e0080000000000d3",          "number": "16",          "repository": {            "id": "repo_01k2ja2000e0080000000000q4",            "name": "rocket",            "owner": {              "slug": "acme",              "id": "ns_01k2ja2000e0080000000000p3",              "type": "team"            }          }        }      },      "version": {        "number": "3",        "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",        "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",        "createdAt": "2026-08-01T09:30:00Z"      }    }  ]}

获取拉取请求

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}
Scoperepository:pull_requests:readAuthInstallation tokenUser access token

返回单个拉取请求，包括其已分配的标签。

已关闭或已合并的拉取请求还可能包含 closedAt、mergedAt 和 mergeCommitSha。将 head.ref 和 base.ref 视为不透明的 Origin 引用字符串；它们可以是短分支名称，也可以是完全限定的 refs/heads/… 值。

路径参数

ownerSlug 字符串 必填

所属实体的唯一 slug。

repoName string 必填

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

pullNumber string 必填

响应字段

id string

Stable Origin 拉取请求标识符。

number string

代码仓库内的拉取请求编号，以 JSON 字符串编码。

state string

拉取请求状态：打开或关闭。已合并的拉取请求为关闭状态，且 merged 字段为 true。

draft boolean

该 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 字符串

用户的公开标识符。

author.user.email string

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

author.user.displayName string

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

author.user.handle string

用户声明的个人资料用户名 (不含 @ 前缀) 。仅当该个人资料公开可见时才会显示；否则省略。

author.app 对象

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

author.app.id string

应用的公开标识符。

author.app.displayName string

应用已注册的显示名称。当无法解析应用或该应用是 Cherri Code 的第一方托管主体时，不显示此项。

author.serviceAccount 对象

操作主体的服务帐号变体。由服务帐号执行该操作时设置。

author.serviceAccount.id string

服务账户的公开标识符。

createdAt string

RFC 3339 拉取请求创建时间戳。

updatedAt string

最新拉取请求更新的 RFC 3339 时间戳。

closedAt string

RFC 3339 格式的关闭时间戳；可能出现在已关闭或已合并的拉取请求中。

mergedAt string

RFC 3339 合并时间戳；可能出现在已合并的拉取请求中。

mergeCommitSha string

合并操作写入基分支的提交 SHA。拉取请求合并后设置，合并前不存在。合并前的预览是另一个提交，可通过 pull/<number>/merge 引用，使用获取 Git 引用读取。

additions 整数

当前拉取请求版本中新增的行。

deletions 整数

当前 PR 版本中已删除的行。

changedFiles 整数

当前 PR 版本中已修改的文件数量。

labels array

当前分配给该拉取请求的标签，按名称排序。未分配时为空。

labels[].id string

标签的公共标识符。

labels[].name string

标签名称，在仓库中唯一。写入端点使用名称来定位该标签。

labels[].color string

不含前导 # 的六位十六进制颜色值。

labels[].description string

标签描述。若标签无描述，则不返回此字段。

stack 对象

分支栈成员关系：此拉取请求所属的依赖拉取请求链，每个请求都叠加在其所基于的上一个请求之上。若该拉取请求不属于任何分支栈，则不包含此字段。

stack.id string

稳定的分支栈标识符，由该分支栈的所有成员共享。将其作为 stackId 传给 List Pull Requests 即可读取其他成员。

stack.parentPullRequest 对象

此拉取请求所依附的上层拉取请求。在栈的根节点不存在。已合并的父 PR 会一直被引用，直到子 PR 被重新定向目标或重新指定父级。

stack.parentPullRequest.id string

父拉取请求 (PR) 的稳定 Origin 标识符。

stack.parentPullRequest.number string

父级拉取请求在代码仓库内的编号，以 JSON 字符串编码。

stack.parentPullRequest.repository 对象

parent 所属的代码仓库，包含与 check run 的 repository 相同的 id、name 和 owner 字段。分支栈不会跨仓库，因此这里始终是该拉取请求自身所在的代码仓库。

version 对象

当前编号的拉取请求版本及其 head/base SHA。

version.number string

单调递增的拉取请求版本号，编码为 JSON 字符串。

version.headSha string

此拉取请求版本记录的 Head SHA。

version.baseSha string

此 PR 版本记录的基准 SHA。

version.createdAt string

此拉取请求版本创建时间的 RFC 3339 时间戳。

version.potentialMergeCommit 对象

Origin 对此版本的测试合并，即将其 headSha 合并到基分支最新提交上的那个提交，以及该测试合并的准备进度。每个版本都包含此信息。它仅描述当前版本，在拉取请求合并后仍可读取；它与 mergeCommitSha 是不同的提交。对于堆叠式拉取请求，基分支是父级拉取请求的分支，因此测试合并只涵盖此拉取请求在该分支基础上的更改。

version.potentialMergeCommit.state string

测试合并的准备进度。允许的值：unknown、prepared、merge_conflict。unknown 表示测试合并尚未准备好：该版本正在等待准备，或者准备过程超时或失败。每个新版本最初都处于 unknown 状态，因此不会沿用其他版本的提交。prepared 表示测试合并已生成，sha 和 baseSha 用于描述该合并。merge_conflict 表示将 headSha 合并到基分支的最新提交时发生冲突，因此未生成测试合并；获取 PR 的可合并性 会将这种情况报告为 merge_conflict 阻塞因素。重新打开 PR 后，会再次为该版本准备测试合并。将无法识别的值视为 unknown。

version.potentialMergeCommit.sha string

双父级测试合并提交的 SHA：第一个父级为此对象的 baseSha，第二个父级为该版本的 headSha。仅当 state 为 prepared 时存在。在此版本仍为最新版本期间，pull/{pullNumber}/merge 引用指向该提交。此后仍可通过获取提交按 SHA 读取该提交，但无法通过 Git 按 SHA 获取。

version.potentialMergeCommit.baseSha string

构建测试合并所依据的基分支最新提交。仅当 state 为 prepared 时提供。它可能比 version.baseSha 更新；如果基分支只是向前推进，Origin 不会刷新此值。
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": "add-telemetry-schema",    "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"  },  "author": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "[email protected]"    }  },  "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"    }  ],  "stack": {    "id": "stk_01k2ja2000e0080000000000s1",    "parentPullRequest": {      "id": "pr_01k2ja2000e0080000000000d3",      "number": "16",      "repository": {        "id": "repo_01k2ja2000e0080000000000q4",        "name": "rocket",        "owner": {          "slug": "acme",          "id": "ns_01k2ja2000e0080000000000p3",          "type": "team"        }      }    }  },  "version": {    "number": "3",    "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8",    "createdAt": "2026-08-01T09:30:00Z",    "potentialMergeCommit": {      "state": "prepared",      "sha": "c7b6a5948372615049f8e7d6c5b4a3928170605f",      "baseSha": "5e2d1c0b9a8f7e6d5c4b3a2918070605f4e3d2c1"    }  }}

创建拉取请求

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 或省略时，创建为开放状态 (可供评审) 。

parentPullRequest 对象

可选的堆栈父项：同一仓库中另一个处于打开或草稿状态的拉取请求。必须恰好设置一个成员。选择器为空、成员超过一个或使用 clear 时，将返回 InvalidArgument (HTTP 400)。

parentPullRequest.number string

仓库中的父拉取请求编号。

parentPullRequest.id string

父 PR 的 ID，即 id 返回的值。

响应字段

id string

Stable Origin 拉取请求标识符。

number string

以 JSON 字符串编码的仓库本地拉取请求编号。

state string

拉取请求状态；打开或关闭。已合并的拉取请求为关闭状态，且 merged 设置为 true。

draft 布尔值

该拉取请求是否为草稿。

merged boolean

拉取请求是否已合并。

title string

拉取请求标题。

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 的应用变体。当应用执行该操作时设置。

author.app.id string

应用的公开标识符。

author.app.displayName string

应用注册的显示名称。若无法解析该应用，或该应用是 Cherri Code 的第一方托管主体，则不显示。

author.serviceAccount object

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

author.serviceAccount.id string

服务账户的公开标识符。

createdAt string

RFC 3339 格式的拉取请求创建时间戳。

updatedAt string

最新拉取请求更新的 RFC 3339 时间戳。

closedAt string

RFC 3339 格式的关闭时间戳；可能出现在已关闭或已合并的拉取请求中。

mergedAt string

RFC 3339 合并时间戳；可能显示在已合并的拉取请求上。

mergeCommitSha string

合并操作写入基础分支的提交 SHA。拉取请求合并后才会设置此字段，此前不存在。合并前的预览对应另一个提交，可通过 pull/<number>/merge 引用并使用 获取 Git 引用 读取。

additions 整数

当前 PR 版本新增的行。

deletions 整数

当前 PR 版本中已删除的行。

changedFiles 整数

当前 PR 版本中已更改的文件数量。

labels 数组

当前分配给拉取请求的标签，按名称排序。若未分配则为空。

labels[].id string

标签的公开标识符。

labels[].name string

标签名称，在仓库中必须唯一。写入端点通过名称引用该标签。

labels[].color string

不含前导 # 的六位十六进制颜色值。

labels[].description string

标签描述。如标签无描述则不返回此字段。

stack 对象

分支栈成员关系：此拉取请求所属的依赖拉取请求链，每个请求都叠加在其所依赖的请求之上。若拉取请求不属于任何分支栈，则不返回此字段。

stack.id string

由堆栈中每个成员共享的稳定标识符。将其作为 stackId 传递给 列出拉取请求 以读取其他成员。

stack.parentPullRequest 对象

此 PR 所叠加的上层 PR。位于栈根部时不存在此字段。已合并的父级 PR 仍会保持引用，直到子级被重新指定目标或重新设置父级。

stack.parentPullRequest.id string

父级拉取请求的 Stable Origin 标识符。

stack.parentPullRequest.number string

以 JSON 字符串编码的仓库本地父拉取请求编号。

stack.parentPullRequest.repository 对象

父级所属的代码仓库，其 id、name 和 owner 字段与检查运行 (check run) 的 repository 相同。堆栈不会跨仓库，因此这始终是该拉取请求所属的仓库。

version object

当前带编号的拉取请求版本及其 head/base SHA。

version.number string

单调递增的拉取请求版本号，以 JSON 字符串形式编码。

version.headSha string

此拉取请求版本记录的 Head SHA。

version.baseSha string

此拉取请求版本记录的基础 SHA。

version.createdAt string

该拉取请求版本创建时间的 RFC 3339 时间戳。

version.potentialMergeCommit object

Origin 对此版本的测试合并：将其 headSha 合并到基础分支顶端所生成的提交，以及该测试合并的准备进度。每个版本都会显示此字段。它仅描述此版本，在拉取请求合并后仍可读取；该提交不同于 mergeCommitSha。对于堆叠式拉取请求，基础分支是父级拉取请求的分支，因此测试合并仅涵盖此拉取请求在该分支之上的更改。

version.potentialMergeCommit.state string

测试合并的准备进度。允许的值：unknown、prepared、merge_conflict。unknown 表示测试合并尚未准备好：该版本仍在等待准备，或准备过程超时或失败。每个新版本的初始状态都是 unknown，因此不会沿用其他版本的提交。prepared 表示测试合并已生成，sha 和 baseSha 描述了该测试合并。merge_conflict 表示将 headSha 合并到基础分支的最新提交时发生冲突，因此没有测试合并；获取拉取请求的可合并性 会将此情况报告为 merge_conflict 阻塞因素，重新打开拉取请求会再次准备该版本。将无法识别的值视为 unknown。

version.potentialMergeCommit.sha string

双亲测试合并提交的 SHA：第一个父提交是此对象的 baseSha，第二个父提交是该版本的 headSha。仅当 state 为 prepared 时返回。当此版本为最新版本时，pull/{pullNumber}/merge 引用指向该提交。此后仍可通过 获取提交 按 SHA 读取，但无法通过 Git 按 SHA 获取。

version.potentialMergeCommit.baseSha string

构建测试合并时所依据的基础分支顶端提交。仅当 state 为 prepared 时返回。它可能比 version.baseSha 更新；基础分支仅向前推进时，源站不会更新它。
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": "[email protected]"    }  },  "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

更新拉取请求的标题、正文、基础分支、栈父级和/或生命周期状态。

省略的字段保持不变。已提供的字段按以下顺序应用：元数据，然后是重新打开/草稿/准备审查，然后是基础分支，然后是堆栈父项，最后是关闭操作。关闭操作最后执行，因此同一请求中的重新指定目标仍能看到处于打开状态的更改；重新打开操作在基础分支之前执行，因此已关闭的拉取请求可以重新指定目标；堆栈父项在基础分支之后执行，因此显式指定的父项优先于基础分支更改所推导出的父项。如果后续步骤失败，前面的步骤可能已经提交。

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" 会将其标记为可供审查，包括发布已有草稿。若拉取请求在关闭期间其 head 发生变化，重新打开时会记录新的 version 并发送 pull_request.head_ref.pushed。已合并状态不可写；请使用 MergePullRequest。

draft 布尔值

true 将拉取请求标记为草稿；false 将其标记为可供审查 (若当前已关闭，则会重新打开，并可能记录一个新的 version) 。当 state 为 "closed" 时忽略。

base string

新的基准分支。重新指定拉取请求的目标分支；当新基准是另一项更改的头部 (或默认分支) 时，还可以更新堆栈的父级关系。必须指定调用时仓库中存在的分支；提交 SHA、标签名或不存在的分支将返回 InvalidArgument (HTTP 400) 。

parentPullRequest 对象

编辑堆栈父项。只能设置一个成员：number 或 id 会将此拉取请求堆叠在该父项之上，并替换任何现有父项；clear 则会移除父项。省略此字段可保持堆栈不变。空选择器、clear: false 或设置多个成员会返回 InvalidArgument (HTTP 400) 。这只是建立关联：不会重写任何分支；只有同时发送 base 时，才会重新指定 base。Origin 会在应用 base 后应用此更改，因此显式指定的父项优先于由 base 更改推导出的父项。

parentPullRequest.number string

仓库中父拉取请求的编号。

parentPullRequest.id string

父 PR 的 ID，如在 id 字段中返回。

parentPullRequest.clear 布尔值

移除当前堆栈的父项。仅接受 true。

响应字段

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

该变更最新版本中此侧的 tip 提交 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

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

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。在拉取请求合并后设置，合并前不存在。合并前的预览是另一个提交，可通过 获取 Git 引用 读取 pull/<number>/merge 引用。

additions 整数

当前 PR 版本中新增的行。

deletions 整数

当前拉取请求版本中已删除的行。

changedFiles 整数

当前 PR 版本中已更改的文件数。

labels 数组

当前分配给拉取请求的标签，按名称排序。未分配则为空。

labels[].id string

标签的公开标识符。

labels[].name string

标签名称，在仓库内唯一。写入端点通过名称引用该标签。

labels[].color string

不含前导 # 的六位十六进制颜色值。

labels[].description string

标签描述。若标签无描述则不返回此字段。

stack 对象

分支栈归属：该 PR 所属的依赖 PR 链，每个 PR 都叠加在其所基于的 PR 之上。当该 PR 不属于任何分支栈时，不会包含此字段。

stack.id string

分支栈中所有成员共用的稳定标识符。将其作为 stackId 传递给 列出拉取请求 以读取其他成员。

stack.parentPullRequest 对象

此拉取请求所基于的拉取请求。位于堆栈根部时不存在此字段。已合并的父级会继续保持引用状态，直到子级更改目标或重新指定父级。

stack.parentPullRequest.id string

父级 PR 的 Stable Origin 标识符。

stack.parentPullRequest.number string

以 JSON 字符串编码的父拉取请求在仓库中的本地编号。

stack.parentPullRequest.repository 对象

父项所属的代码仓库，具有与检查运行的 repository 相同的 id、name 和 owner 字段。分支栈不会跨越代码仓库，因此这始终是该拉取请求自身的代码仓库。

version 对象

当前带编号的拉取请求版本及其 head/base SHA。

version.number string

编码为 JSON 字符串的单调递增的拉取请求版本号。

version.headSha string

此拉取请求版本记录的 Head SHA。

version.baseSha string

此 PR 版本记录的基准 SHA。

version.createdAt string

此 PR 版本创建时的 RFC 3339 时间戳。

version.potentialMergeCommit 对象

Origin 对此版本的测试合并：将该版本的 headSha 合并到基准分支最新提交上所生成的提交，以及该测试合并的准备进度。每个版本都包含此字段。它仅描述此版本，即使拉取请求合并后仍可读取；该提交与 mergeCommitSha 不同。对于堆叠式拉取请求，基准分支是父级拉取请求的分支，因此测试合并仅涵盖此拉取请求在该分支基础上所做的更改。

version.potentialMergeCommit.state string

测试合并的准备进度。允许的值：unknown、prepared、merge_conflict。unknown 表示测试合并尚未准备就绪：该版本仍在等待准备，或准备过程已超时或失败。每个新版本的初始状态都是 unknown，因此不会沿用其他版本的提交。prepared 表示测试合并已生成，sha 和 baseSha 用于描述该合并。merge_conflict 表示将 headSha 合并到基础分支的最新提交时发生冲突，因此未生成测试合并；获取拉取请求的可合并性 会将此情况报告为 merge_conflict 阻塞因素。重新打开拉取请求后，会再次为该版本准备测试合并。将无法识别的值视为 unknown。

version.potentialMergeCommit.sha string

双父测试合并提交的 SHA：其第一个父提交是此对象的 baseSha，第二个父提交是该版本的 headSha。仅当 state 为 prepared 时提供。当此版本是最新版本时，pull/{pullNumber}/merge 引用指向该提交。之后仍可通过 获取提交 按 SHA 读取该提交，但无法通过 Git 按 SHA 获取。

version.potentialMergeCommit.baseSha string

构建测试合并时所基于的基准分支最新提交。仅当 state 为 prepared 时提供。它可能比 version.baseSha 更新；如果基准分支只是向前推进，源站不会刷新它。
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": "[email protected]"    }  },  "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 的不透明游标。请求第一页时请省略。后续请求中的 pageSize 仅对该页生效；省略则沿用上一页的分页大小。

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.path string

线程差异锚点所在的文件路径。一般讨论线程则为空。

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

应用的注册显示名称。当应用无法解析，或该应用是 Cherri Code 第一方托管的执行主体时，不显示。

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

来源所有者标识符。

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"        },        "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": "[email protected]"        }      },      "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"      }    }  }}

获取拉取请求评论

GET/v1/origin/repos/{ownerSlug}/{repoName}/pulls/comments/{commentId}
Scoperepository:pull_requests:reviews:readAuthInstallation tokenUser access token

根据稳定的 Origin ID 返回单条拉取请求评论。位于已授权仓库之外的评论，或调用方不可见的待审评论，将返回 404。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

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

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.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

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

author.user.displayName string

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

author.user.handle string

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

author.app object

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

author.app.id string

应用的公开标识符。

author.app.displayName string

应用注册的显示名称。若无法解析该应用，或该应用是 Cherri Code 的第一方托管主体，则省略。

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"    },    "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": "[email protected]"    }  },  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z"}

删除 PR 评论

DELETE/v1/origin/repos/{ownerSlug}/{repoName}/pulls/comments/{commentId}
Scoperepository:pull_requests:reviews:writeAuthInstallation tokenUser access token

通过其稳定的 Origin ID 删除 PR 评论。响应体为空。

评论作者始终可以删除自己的评论。其他调用方必须拥有代码仓库写入权限，repository:contents:write 会授予此权限；否则将收到 PermissionDenied (HTTP 403)。删除线程中的最后一条评论会移除该线程；删除其他任何评论 (包括发起该线程的评论) 时，线程及其剩余评论将保留。线程是否已解决不影响此操作。该评论的表情回应和编辑历史也会随之删除。

未知 ID、已删除的评论以及其他代码仓库中的评论均返回 404。格式错误的 ID 返回 InvalidArgument (HTTP 400)。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

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

commentId string 必填

响应字段

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

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

响应：

204 No Content

创建拉取请求评论

POST/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/comments
Scoperepository:pull_requests:reviews:writeAuthInstallation tokenUser access token

在 Origin 拉取请求上创建一条评论。评论恰好针对以下四种目标之一：threadId 用于回复现有讨论线程，无论是常规讨论还是内联讨论；inline 用于在拉取请求版本的差异中，针对某个行范围开启新讨论线程；file 用于在该差异中的整个文件上开启新讨论线程；如果以上三项均未提供，则开启一个新的常规讨论线程。正文超过 65,536 个字符时，将返回 InvalidArgument (HTTP 400) 错误。

inline 锚点必须引用该版本的 diff。path 必须属于该 diff，且锚定侧必须有内容，因此在新增文件上将 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.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

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

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"    },    "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": "[email protected]"    }  },  "createdAt": "2026-08-01T09:30:00Z",  "updatedAt": "2026-08-02T14:45:00Z"}

更新拉取请求评论

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.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

应用已注册的显示名称。当该应用无法解析或为 Cherri Code 的第一方托管主体时将省略。

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"    },    "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": "[email protected]"    }  },  "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。可以使用 创建拉取请求评论 回复已解决的线程，这不会重新打开该线程。

路径参数

ownerSlug string 必填

所属实体的唯一 slug。

repoName string 必填

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

threadId string 必填

稳定的 Origin 线程 ID。

请求体

resolved boolean 必填

目标解决状态。true 表示将该线程标记为已解决；false 表示重新打开该线程。

响应字段

id string

线程的稳定标识。可按此值将同一讨论中的评论归为一组。

version object

该线程所针对的拉取请求版本，包括其 head 和 base 的 SHA。锚点固定于此版本，不会随着拉取请求新增版本而变动。

version.number string

单调递增的拉取请求版本号，以 JSON 字符串形式编码。

version.headSha string

该拉取请求版本记录的 Head SHA。

version.baseSha string

此拉取请求版本捕获的基础 SHA。

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"  },  "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 条提交。页面令牌会固定拉取请求版本和提交游标；若令牌与当前的 head 或 base 不再匹配，则返回 400。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

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

pullNumber string 必填

查询参数

pageSize 整数

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

pageToken string

来自上一次响应中 next_page_token 的不透明游标。首页请求时留空。该 token 与代码仓库、拉取请求版本和提交偏移量绑定。后续请求中的 pageSize 作用于该页；省略时沿用上一页的每页数量。

响应字段

commits 数组

精简版提交信息，不含统计数据，总计最多显示 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 string

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": "[email protected]",          "date": "2026-08-01T09:30:00Z"        },        "committer": {          "name": "Jane Doe",          "email": "[email protected]",          "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

列出拉取请求中已更改的文件。

返回文件名、状态、行数统计、补丁以及可选的原文件名。结果默认返回 30 个文件，最多 100 个。页面令牌会固定拉取请求的版本和文件游标；若令牌与当前的 head 或 base 不再匹配，则返回 400。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

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

pullNumber string 必填

查询参数

pageSize 整数

返回的修改文件数量上限。未设置或设为 0 时，默认值为 30。超过 100 的值将限制为 100。

pageToken string

来自上一个响应的 next_page_token 的不透明游标。第一页为空。该 token 与代码仓库、拉取请求版本和变更文件游标绑定。后续请求中的 pageSize 适用于该页；若省略，则沿用上一页的每页数量。

响应字段

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 仓库；不支持镜像仓库。

合并会合入该 PR 最新 version 的 head 提交。如果 head 分支已越过该提交 (例如已有推送完成，但源站尚未将其记录为新版本) ，请求将返回 Aborted (HTTP 409 Conflict) ，与 expectedHeadSha 过期时的响应相同，且不会合并任何内容。请等 获取 PR 在 version.headSha 中返回新的 head 后再重试。

路径参数

ownerSlug string 必填

所属实体的唯一 slug。

repoName string 必填

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

pullNumber string 必填

要合并的 pull 编号。若该 pull 位于堆栈中，此次合并会将从堆栈根到该编号的所有 pull 一并合并。

请求体

expectedHeadSha string

防止合并应用尚未见过的提交头：此处应填写预期的拉取请求当前提交头的完整提交 SHA (40 或 64 个十六进制字符) 。如果提交头已变更，合并将被拒绝，并返回 ABORTED (HTTP 409 Conflict) ，且不会合并任何内容。非完整提交 SHA 的值将被拒绝，并返回 InvalidArgument (HTTP 400) 。省略此项则合并当前提交头。如果拉取请求已合并，则不会进行此项检查，并返回幂等成功。

mergeMethod string

拉取请求的合并方式。允许的值：merge (创建合并提交) 和 squash (创建单个压缩提交) 。如果仓库不允许所选方式，则会返回 FailedPrecondition (HTTP 400) ；如果值为其他内容，则会返回 InvalidArgument (HTTP 400) 。省略此项则使用仓库的默认方式：如果仓库允许合并提交，则创建合并提交；否则使用压缩方式；如果基分支要求线性历史记录，则使用压缩方式。

响应字段

mergeCommitSha string

合并操作写入基础分支的提交 SHA。合并前预览对应另一个提交，可通过 pull/<number>/merge 引用，使用 获取 Git 引用 获取。

mergedPullNumbers 数组

从堆栈根节点到目标节点合并的拉取请求编号 (JSON 字符串) 。

pullRequest 对象

合并后的目标 PullRequest；尽管示例有所简化，声明的响应类型仍是完整资源。

pullRequest.id string

Stable Origin 拉取请求标识符。

pullRequest.number string

代码仓库内的拉取请求编号，以 JSON 字符串形式编码。

pullRequest.state string

Pull request 状态；open 或 closed。已合并的 pull request 会标记为 closed，并将 merged 设为 true。

pullRequest.draft boolean

PR 是否为草稿。

pullRequest.merged boolean

该拉取请求是否已合并。

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 对象

公开发起该拉取请求的用户。

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

应用的注册显示名称。当应用无法解析，或属于 Cherri Code 的第一方托管 actor 时，不显示。

pullRequest.author.serviceAccount 对象

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

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。拉取请求合并后设置，合并前不存在。合并前的预览是另一个提交，可通过 pull/<number>/merge 引用使用 获取 Git 引用 读取。

pullRequest.additions 整数

当前 PR 版本中新增的行。

pullRequest.deletions 整数

当前拉取请求版本中被删除的行。

pullRequest.changedFiles 整数

当前拉取请求版本中更改的文件数。

pullRequest.labels 数组

当前分配给拉取请求的标签，按名称排序。若未分配则为空。

pullRequest.labels[].id string

标签的公开标识符。

pullRequest.labels[].name string

标签名称，在仓库内唯一。写入端点使用名称来引用该标签。

pullRequest.labels[].color string

六位十六进制颜色值，不含前导 #。

pullRequest.labels[].description string

标签描述。标签没有描述时不返回此字段。

pullRequest.stack 对象

堆叠关系：此 PR 所属的依赖 PR 链，其中每个 PR 都叠加在其所依赖的 PR 之上。若此 PR 不属于任何堆叠，则不包含此字段。

pullRequest.stack.id string

稳定的堆栈标识符，由堆栈中的每个成员共享。将其作为 stackId 传递给 列出拉取请求 以读取其他成员。

pullRequest.stack.parentPullRequest 对象

该 PR 所堆叠在其上的 PR。位于堆栈根部时不返回此字段。已合并的父级仍会保持被引用，直到子级被重新指定目标或重新指定父级。

pullRequest.stack.parentPullRequest.id string

父拉取请求的 Stable Origin 标识符。

pullRequest.stack.parentPullRequest.number string

父拉取请求在仓库内的本地编号，已编码为 JSON 字符串。

pullRequest.stack.parentPullRequest.repository 对象

父级所属的代码仓库，包含与 check run 的 repository 相同的 id、name 和 owner 字段。分支栈不会跨仓库，因此这里始终是该拉取请求自身所在的仓库。

pullRequest.version 对象

当前编号对应的 PR 版本及其 head/base SHA。

pullRequest.version.number string

编码为 JSON 字符串的单调递增的拉取请求版本号。

pullRequest.version.headSha string

此拉取请求版本记录的 Head SHA。

pullRequest.version.baseSha string

此拉取请求版本记录的 Base SHA。

pullRequest.version.createdAt string

该拉取请求版本创建时间的 RFC 3339 时间戳。

pullRequest.version.potentialMergeCommit 对象

Origin 为此版本执行的测试合并，即将其 headSha 合并到基础分支最新提交后生成的提交，以及测试合并的准备进度。每个版本都会包含此信息。它仅描述此版本，且在拉取请求合并后仍可读取；它与 mergeCommitSha 是不同的提交。对于堆叠式拉取请求，基础分支是父级拉取请求的分支，因此测试合并仅涵盖此拉取请求基于该分支所做的更改。

pullRequest.version.potentialMergeCommit.state string

测试合并的准备进度。允许的值：unknown、prepared、merge_conflict。unknown 表示测试合并尚未就绪：该版本正在等待准备，或准备已超时或失败。每个新版本的初始状态均为 unknown，因此绝不会带有其他版本的提交。prepared 表示测试合并已存在，其信息由 sha 和 baseSha 给出。merge_conflict 表示将 headSha 合并到基础分支顶端时发生冲突，因此不存在测试合并；获取 PR 可合并性 会将此情况报告为 merge_conflict 阻塞因素，重新打开该 PR 会重新准备该版本。遇到无法识别的值时，应按 unknown 处理。

pullRequest.version.potentialMergeCommit.sha string

双父测试合并提交的 SHA：其第一个父提交是此对象的 baseSha，第二个父提交是该版本的 headSha。仅当 state 为 prepared 时才会提供。此版本为最新版本期间，pull/{pullNumber}/merge 引用指向该提交。此后仍可通过 获取提交 根据 SHA 读取该提交，但无法通过 Git 根据 SHA 获取。

pullRequest.version.potentialMergeCommit.baseSha string

构建测试合并所依据的基础分支顶端提交。仅当 state 为 prepared 时提供。该提交可能比 pullRequest.version.baseSha 更新；如果基础分支只是向前推进，Origin 不会刷新此值。
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": "[email protected]"      }    },    "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": "[email protected]"    }  ],  "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": "[email protected]"    }  ],  "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 的不透明游标。请求第一页时请省略。后续请求中的 pageSize 作用于该页；省略则沿用之前的每页大小。

响应字段

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

应用注册的显示名称。当无法解析该应用，或该应用属于 Cherri Code 的第一方托管主体 (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[].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

应用注册的显示名称。当无法解析该应用，或该应用属于 Cherri Code 的第一方托管主体 (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

来源所有者标识符。

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": "[email protected]"        }      },      "verdict": "approve",      "body": "Approving. The telemetry schema matches the spec.",      "submittedAt": "2026-08-02T15:00:00Z",      "pullRequestVersion": {        "number": "3",        "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",        "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"      }    }  ],  "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

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

author.user.displayName string

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

author.user.handle string

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

author.app 对象

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

author.app.id string

应用的公开标识符。

author.app.displayName string

应用已注册的显示名称。无法解析该应用或该应用属于 Cherri Code 第一方托管 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

此拉取请求版本记录的基础 SHA。

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

应用已注册的显示名称。无法解析该应用时，以及对于 Cherri Code 的第一方托管 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": "[email protected]"    }  },  "verdict": "approve",  "body": "Approving. The telemetry schema matches the spec.",  "submittedAt": "2026-08-02T15:00:00Z",  "pullRequestVersion": {    "number": "3",    "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"  }}

更新拉取请求审查

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

应用已注册的显示名称。当无法解析该应用或该应用属于 Cherri Code 的第一方托管主体时，将省略此名称。

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。

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

应用已注册的显示名称。当应用无法解析或该应用属于 Cherri Code 的第一方托管主体时，将省略此名称。

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": "[email protected]"    }  },  "verdict": "approve",  "body": "Approving. The telemetry schema matches the spec.",  "submittedAt": "2026-08-02T15:00:00Z",  "pullRequestVersion": {    "number": "3",    "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"  }}

关闭拉取请求评审

PUT/v1/origin/repos/{ownerSlug}/{repoName}/pulls/{pullNumber}/reviews/{reviewId}/dismissals
Scoperepository:pull_requests:reviews:writeAuthInstallation tokenUser access token

撤销已提交的评审，使其裁定不再计入拉取请求的评审状态。评审本身会被保留，并继续出现在 ListPullRequestReviews 中，且 dismissal 已设置。

撤销评审不要求操作者是该评审的作者；只需拥有对该代码仓库拉取请求评审的写入权限即可。

只有 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

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

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。

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

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

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": "[email protected]"    }  },  "verdict": "approve",  "body": "Approving. The telemetry schema matches the spec.",  "submittedAt": "2026-08-02T15:00:00Z",  "pullRequestVersion": {    "number": "3",    "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",    "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"  },  "dismissal": {    "dismissedBy": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "[email protected]"      }    },    "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

以十进制字符串编码的数字 Cherri Code 用户 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

根据稳定的 源站 ID 删除代码仓库规则集。响应体为空。

未知代码仓库和未知规则集均返回 404，消息会区分二者。存储在其他代码仓库中的规则集会被视为未知规则集。空 rulesetId 返回 InvalidArgument (HTTP 400)。

路径参数

ownerSlug string 必填

所有者实体的唯一 slug。

repoName string 必填

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

rulesetId string 必填

稳定的 源站 规则集 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

SSH 证书颁发机构

SSH 证书颁发机构是所有者所信任的公钥：由它签发的用户证书可用于认证该所有者仓库上的 Git over SSH 操作，因此所属团队的成员无需注册 SSH 密钥即可通过 SSH 使用 git。这些端点用于列出所有者信任的证书颁发机构、添加和移除证书颁发机构，以及设置所有者是否强制要求使用证书。证书颁发机构隶属于团队拥有的所有者；添加时的重复检查仅在该所有者范围内进行，而不是针对整个源站，因此多个所有者可以信任同一个证书颁发机构。

列出操作支持安装令牌和用户令牌。添加、移除证书颁发机构以及设置证书要求，需要使用具有 namespace:settings:write 权限的 Cherri Code 用户凭据；不支持应用令牌和安装令牌。

列出 SSH 证书颁发机构

GET/v1/origin/owners/{ownerSlug}/ssh-certificate-authorities
Scopenamespace:settings:readAuthInstallation tokenUser access token

列出所有者在通过 SSH 使用 git 时信任的 SSH 证书颁发机构 (按从新到旧排列) ，并返回该所有者是否要求使用证书。响应不分页，会返回全部颁发机构。

路径参数

ownerSlug string 必填

要列出其颁发机构的所有者的 slug。

响应字段

certificateAuthorities array

所有者信任的全部颁发机构，按从新到旧排列。

certificateAuthorities[].id string

颁发机构的标识符；删除 SSH 证书颁发机构接口将其作为 certificateAuthorityId 参数传入。

certificateAuthorities[].name string

添加颁发机构时指定的标签。

certificateAuthorities[].keyType string

颁发机构公钥的 OpenSSH 密钥类型，例如 ssh-ed25519。

certificateAuthorities[].fingerprint string

公钥的 SHA-256 指纹，格式为 SHA256:<base64>，与 ssh-keygen -l 的输出格式一致。

certificateAuthorities[].publicKey string

颁发机构的公钥，格式为 <key_type> <base64>，不含注释。

certificateAuthorities[].createdAt string

添加颁发机构的时间，采用 RFC 3339 时间戳格式。

requireCertificates boolean

所有者是否要求使用 SSH 证书；参见设置 SSH 证书要求。
curl --request GET \  --url 'https://api.cursor.com/v1/origin/owners/OWNER_SLUG/ssh-certificate-authorities' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应结构：

{  "certificateAuthorities": [    {      "id": "nsca_01k2ja2000e0080000000000s5",      "name": "Acme production CA",      "keyType": "ssh-ed25519",      "fingerprint": "SHA256:D5vlIclvaSZlwq4gmckavfLE7n7F542Eyhk/PvXkRq0",      "publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPwoQNzBuiWhDF4EKwRyt8h48XRY7Bc4yWbQ9s3Tnj7Q",      "createdAt": "2026-08-02T14:45:00Z"    }  ],  "requireCertificates": true}

添加 SSH 证书颁发机构

POST/v1/origin/owners/{ownerSlug}/ssh-certificate-authorities
Scopenamespace:settings:writeAuthUser access token

为所有者添加一个受信任的 SSH 证书颁发机构，并返回该机构。之后，所属团队的成员无需注册 SSH 密钥，即可使用该机构签发的用户证书，通过 SSH 对该所有者的仓库执行 git 操作。

publicKey 是该颁发机构自身的公钥，格式为一行 OpenSSH authorized_keys。如果传入的是证书、不支持的密钥类型或小于 2048 位的 RSA 密钥，则返回 InvalidArgument (HTTP 400) 。如果该所有者已添加过此密钥，则返回 AlreadyExists (HTTP 409 Conflict) ；该检查仅限于当前所有者，因此多个所有者可以信任同一颁发机构。颁发机构只能添加到团队拥有的所有者；对其他任何所有者均返回 FailedPrecondition (HTTP 400) 。

调用方必须是持有 namespace:settings:write 的 Cherri Code 用户凭据。不接受应用令牌和安装令牌。

路径参数

ownerSlug string 必填

所有者 slug。

请求体

publicKey string 必填

颁发机构的公钥，格式为一行 OpenSSH authorized_keys (<key_type> <base64> [comment]) 。支持的密钥类型包括 ssh-ed25519、ecdsa-sha2-nistp256、ecdsa-sha2-nistp384、ecdsa-sha2-nistp521，以及模数不少于 2048 位的 ssh-rsa。不接受证书。

name string 必填

颁发机构的标签，最多 255 个字符。

响应字段

id string

颁发机构的标识符；在删除 SSH 证书颁发机构中作为 certificateAuthorityId 传入。

name string

添加颁发机构时指定的标签。

keyType string

颁发机构公钥的 OpenSSH 密钥类型，例如 ssh-ed25519。

fingerprint string

公钥的 SHA-256 指纹，格式为 SHA256:<base64>，与 ssh-keygen -l 的输出格式一致。

publicKey string

颁发机构的公钥，格式为 <key_type> <base64>，不含注释。

createdAt string

添加颁发机构时的 RFC 3339 时间戳。
curl --request POST \  --url 'https://api.cursor.com/v1/origin/owners/OWNER_SLUG/ssh-certificate-authorities' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPwoQNzBuiWhDF4EKwRyt8h48XRY7Bc4yWbQ9s3Tnj7Q acme-ssh-ca",  "name": "Acme production CA"}'

响应结构：

{  "id": "nsca_01k2ja2000e0080000000000s5",  "name": "Acme production CA",  "keyType": "ssh-ed25519",  "fingerprint": "SHA256:D5vlIclvaSZlwq4gmckavfLE7n7F542Eyhk/PvXkRq0",  "publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPwoQNzBuiWhDF4EKwRyt8h48XRY7Bc4yWbQ9s3Tnj7Q",  "createdAt": "2026-08-02T14:45:00Z"}

删除 SSH 证书颁发机构

DELETE/v1/origin/owners/{ownerSlug}/ssh-certificate-authorities/{certificateAuthorityId}
Scopenamespace:settings:writeAuthUser access token

从所有者中移除一个 SSH 证书颁发机构。该颁发机构签发的所有证书都将随之失效。若所有者要求使用证书，则无法移除其最后一个颁发机构，请求将返回 FailedPrecondition (HTTP 400) 。响应体为空。

调用方必须使用持有 namespace:settings:write 权限的 Cherri Code 用户凭据。不接受 App 令牌和安装令牌。

路径参数

ownerSlug string 必填

所有者 slug。

certificateAuthorityId string 必填

要移除的颁发机构的 id。

响应字段

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

curl --request DELETE \  --url 'https://api.cursor.com/v1/origin/owners/OWNER_SLUG/ssh-certificate-authorities/CERTIFICATE_AUTHORITY_ID' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN'

响应：

204 No Content

设置 SSH 证书要求

POST/v1/origin/owners/{ownerSlug}/ssh-certificate-authorities:setRequirement
Scopenamespace:settings:writeAuthUser access token

设置所有者是否要求使用 SSH 证书，并返回该所有者的此项设置。启用该要求后，所有者仓库上的 Git over SSH 操作仅接受由其证书颁发机构签发的证书：用户注册的 SSH 密钥将被拒绝，通过 HTTPS 使用的用户 API 密钥也会被拒绝。启用证书要求前，必须至少已列出一个证书颁发机构，否则请求将返回 FailedPrecondition (HTTP 400) 。若设置值与当前值相同，请求会成功，但不做任何更改。

调用方必须是持有 namespace:settings:write 的 Cherri Code 用户凭据。不接受应用令牌和安装令牌。

路径参数

ownerSlug string 必填

所有者 slug。

请求体

requireCertificates boolean 必填

为 true 时要求所有者的仓库使用 SSH 证书，为 false 时取消该要求。

响应字段

requireCertificates boolean

所有者是否要求 Git over SSH 操作使用 SSH 证书。
curl --request POST \  --url 'https://api.cursor.com/v1/origin/owners/OWNER_SLUG/ssh-certificate-authorities:setRequirement' \  --header 'Authorization: Bearer YOUR_ORIGIN_TOKEN' \  --header 'Content-Type: application/json' \  --data '{  "requireCertificates": true}'

响应结构：

{  "requireCertificates": true}

Webhooks

源站 会向应用已注册的 HTTPS webhook URL 发送已签名的 HTTP POST 请求，内容类型为 application/json。

投递至少一次。使用 webhook-id 对重试请求去重，持久化接收请求，快速返回 2xx，并异步处理事件。

源站 等待接收方响应请求头的时间为 10 秒。该时限涵盖 DNS 解析、建立连接、TLS 握手以及直至响应返回的耗时，并适用于每一次尝试。超出该时限的尝试会被记录为传输错误，并按 重试 计划进行重试。反复失败可能会自动禁用投递。

若要在任何真实事件到达接收方之前确认其是否正常工作，请调用 Ping Webhook。

源站 会为镜像仓库投递事件，安装事件负载会在所选代码仓库数组中列出这些代码仓库。投递不会扩大安装可调用的范围：请参阅 镜像仓库。

请求头

请求头描述
content-typeapplication/json
user-agentCherri Code-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>"))

使用有效的源站 JWKS 密钥，验证该十六进制摘要的 UTF-8 字节所对应的 Ed25519 签名。拒绝与当前时间相差超过五分钟的时间戳。

Standard Webhooks 库无法验证源站的 webhook 投递。虽然这些请求头沿用了 Standard Webhooks 的命名，但源站签名的是 SHA-256 摘要，而非被签名的内容本身，并且使用的是 Standard Webhooks 规范中未定义的 v1ed 版本标签。请按上述构造方式进行验证，具体可参考以下示例。

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 标识底层域名事件。

重试

对于传输错误、429 和 5xx 响应，源站最多重试七次。其他 4xx 响应不会重试。

第一次尝试为原始发送。其后的六次重试依次等待 5 秒、30 秒、1 分钟、2 分钟、4 分钟和 8 分钟。

若接收方在每次尝试中都失败，则会在约 16 分钟内收到七次 POST。每次尝试的 webhook-id 保持不变，请据此去重。

自动禁用

所有者可以在应用设置中暂停该应用的 webhook 投递。此外，当接收端在 72 小时窗口内至少 20 轮投递失败、该窗口内没有任何一次投递成功，且失败涉及多个安装方命名空间时，源站也会自动将其禁用。

投递将一直停止，直到所有者手动恢复。此时 Batch Redeliver Webhook Deliveries 会返回 FailedPrecondition (HTTP 400) ，并且不会将任何内容加入队列。API 没有提供表示暂停状态的字段，因此请将该 FailedPrecondition 作为判断依据。

通过 Update App 清除应用的 webhookUrl 则是另一项独立操作。它会取消待投递的事件，即使之后重新设置 URL，这些投递也不会恢复。

恢复

使用 应用 JWT 查询 GET /app/webhook/deliveries。可按投递状态、事件类型、安装、时间范围或页面 token 进行筛选。delivered=false 会返回接收方从未以 2xx 状态码确认的所有投递记录。投递记录可查询七天，因此请在此时间窗口内恢复。

使用 POST /app/webhook/deliveries:batchRedeliver 可将最多 100 个投递 ID 加入重新投递队列。该操作会对 ID 去重，并返回每个投递的结果。已暂停或自动禁用的应用会以 FailedPrecondition (HTTP 400) 拒绝该调用，且不会有任何内容加入队列。

Webhooks 参考

这里列出 源站 投递的所有事件，并逐个字段说明每个事件的负载。有关订阅机制、请求头、签名验证、投递封装、重试计划和自动禁用，请参见 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 之间没有共同历史而由 源站 关闭的情况。
pull_request.mergedPR 合并时。
pull_request.reopened已关闭的 PR 重新打开时。
pull_request.published草稿 PR 变为开放状态时。
pull_request.label.added为 PR 分配标签时。
pull_request.label.removed取消分配 PR 的标签时，包括标签定义被删除的情况。
pull_request.comment.created创建可见的 PR 评论时。
pull_request.comment.reaction.added在 PR 评论中添加回应时。再次添加反应者已有的回应时，会再次投递此事件。
pull_request.comment.reaction.removed从 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.* 事件会发送给应用本身，而非代码仓库订阅。源站 始终会发送这些事件，因此它们不会出现在应用的可选择事件列表中。本表中的其他所有事件都是代码仓库范围的订阅。

新建的应用默认不订阅任何代码仓库范围的事件。请在应用设置中选择所需事件，或通过 Create App 或 Update App 的 events 字段进行设置。源站 仅会将事件投递给同时满足以下条件的应用：已订阅该事件、已设置 Webhook URL，且其安装覆盖该代码仓库并具备该事件所需的作用域。否则既不会投递，也不会报错：不发送任何内容，列出 Webhook 投递记录 中也不会出现相应记录。

对于从 GitHub 镜像而来的代码仓库，源站 不会投递 repository.pushed。这些推送归 GitHub 所有，并由其发送自己的推送 Webhook，因此 源站 再投递一次会造成重复。对原生 源站 仓库以及出站镜像的推送会照常投递，镜像状态不会影响任何其他事件。对于从 GitHub 镜像而来的代码仓库，repository.deleted 会被投递：停止同步只会删除 Cherri Code 侧的代码仓库，GitHub 不会为此发送任何事件。

事件负载

每个事件的投递封装会在 payload 字段中携带该事件的负载对象。结构相同的事件属于同一负载系列；下面每个系列均列出了使用该负载的事件、其字段以及一个示例负载，这些内容均由 OpenAPI 规范生成。在该规范中，每个负载 schema 的 x-origin-webhook-events 扩展字段列出了使用该负载的事件。

代码仓库已创建

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 的非快进更新 (新 tip 不是旧 tip 的后代) 。对于创建或删除 ref、快进更新，以及在 Origin 开始跟踪强制推送状态之前观察到的推送，均为 False。

refUpdates[].headCommit 对象

尽力获取的剥离后新 tip 所指向提交的元数据。删除操作、非提交引用、历史推送以及提取失败时未设置。

refUpdates[].headCommit.sha string

refUpdates[].headCommit.author 对象

提交作者或提交者的 Git 身份标识与时间戳。这是记录在提交对象中的身份标识，而非关联的用户账户。

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 对象

提交的作者或提交者的 Git 身份标识与时间戳。这是记录在提交对象中的身份标识，而非已关联的用户账户。

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.user.performedVia 对象

当应用使用安装用户令牌代表该用户执行此 actor 字段所描述的操作时设置。例如，在评论作者字段中，它指创建评论的应用，而不是后来编辑或删除评论的操作者。用户直接执行操作时该字段不存在；委托数据不可用时，该字段也可能不存在。

pusher.user.performedVia.app 对象

代表用户执行操作的应用。

pusher.user.performedVia.app.id string

pusher.user.performedVia.app.displayName string

应用注册的显示名称，存在时不会为空。若负载所属应用无法解析，或 actor 为 Cherri Code 第一方门面 actor，则省略该字段。

pusher.app 对象

pusher.app.id string

pusher.app.displayName string

应用注册的显示名称，存在时不会为空。若负载所属应用无法解析，或 actor 为 Cherri Code 第一方门面 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": "[email protected]",          "date": "2026-08-01T09:30:00Z"        },        "committer": {          "name": "Jane Doe",          "email": "[email protected]",          "date": "2026-08-01T09:30:00Z"        },        "message": "Add launch telemetry"      }    }  ],  "pushedAt": "2026-08-02T14:45:00Z",  "pusher": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "[email protected]"    }  },  "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.updatedpull_request.stack_parent.updated

一次拉取请求生命周期变更。生命周期操作是信封的 event.type；没有单独的操作字段。

负载字段

pullRequest object

拉取请求快照。未包含已分配的标签；可使用 GetPullRequest 读取。

pullRequest.id string

稳定的 Origin 拉取请求标识符。

pullRequest.number string

该 PR 在其代码仓库中的编号。

pullRequest.state string

"open" 或 "closed"。 草稿为 "open"；已合并和已关闭的拉取请求均为 "closed"。

pullRequest.draft boolean

该拉取请求是否仍为草稿。

pullRequest.merged boolean

该 PR 是否已合并。

pullRequest.title string

PR 标题。

pullRequest.body string

PR 描述。

pullRequest.head object

拉取请求的源端 —— 将被合并进来的内容。

pullRequest.head.ref string

这一侧指向的引用，以 Origin 记录的为准。

pullRequest.head.sha string

此侧在该变更最新版本中的最新提交 SHA。对于 base，这是该版本的 base_sha，可能落后于分支当前的最新提交 (参见 PullRequestVersion) 。

pullRequest.base object

PR 的目标端 — 要合入的分支。

pullRequest.base.ref string

这一侧指向的引用，以 Origin 记录的为准。

pullRequest.base.sha string

此侧在该变更最新版本中的最新提交 SHA。对于 base，这是该版本的 base_sha，可能落后于分支当前的最新提交 (参见 PullRequestVersion) 。

pullRequest.author object

创建该拉取请求的主体。

pullRequest.author.user 对象

pullRequest.author.user.id string

pullRequest.author.user.email string 必填

pullRequest.author.user.displayName string

易读的显示名称：账户的名与姓，各自去除首尾空格后以空格连接，与产品 UI 中呈现的名称完全一致。账户没有名称时省略；绝不会根据电子邮件、ID 或任何其他字段拼凑生成。在无法解析出操作主体的 webhook 负载中，该字段也可能缺失。

pullRequest.author.user.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 背后的身份标识) ，不含 @ 前缀。仅在用户的个人资料公开可见时出现；对于未认领 handle 的用户以及非公开个人资料，该字段会被省略。

pullRequest.author.user.performedVia object

当应用使用安装用户令牌代表此用户执行此主体字段所描述的操作时，设置此字段。例如，在评论的作者信息中，此字段指的是创建评论的应用，而不是后来编辑或删除评论的主体。用户直接执行操作时，此字段不存在；无法获取委托数据时，也可能不存在。

pullRequest.author.user.performedVia.app object

代表该用户执行操作的应用。

pullRequest.author.user.performedVia.app.id string

pullRequest.author.user.performedVia.app.displayName string

应用注册的显示名称；若存在则必不为空。对于所属应用无法解析的负载，以及第一方 Cherri Code 门面 actor，此字段会被省略。

pullRequest.author.app 对象

pullRequest.author.app.id string

pullRequest.author.app.displayName string

应用注册的显示名称；若存在则必不为空。对于所属应用无法解析的负载，以及第一方 Cherri Code 门面 actor，此字段会被省略。

pullRequest.author.serviceAccount object

pullRequest.author.serviceAccount.id string

pullRequest.createdAt string

拉取请求开启的时间。RFC 3339 时间戳。

pullRequest.updatedAt string

拉取请求最后更新的时间。RFC 3339 时间戳。

pullRequest.closedAt string

拉取请求关闭或合并的时间；处于打开状态时该字段未设置。RFC 3339 时间戳。

pullRequest.mergedAt string

拉取请求合并的时间；仅在合并后设置。RFC 3339 时间戳。

pullRequest.mergeCommitSha string

合并操作写入基础分支的提交的 SHA；合并后设置，合并前未设置。合并前的预览是 pull/\<number>/merge 引用 (参见 GetGitRef) ，它指向另一个提交。

pullRequest.additions 整数

该拉取请求最新版本新增的行。

pullRequest.deletions 整数

该拉取请求最新版本删除的行。

pullRequest.changedFiles 整数

该 PR 最新版本所改动的文件。

pullRequest.stack 对象

所属分支栈。当该 PR 不属于任何分支栈时不设置。

pullRequest.stack.id string

稳定的堆栈标识符。将其作为 stack_id 传递给 ListPullRequests，以列出该堆栈的成员。

pullRequest.stack.parentPullRequest 对象

此拉取请求所依赖的上层拉取请求。对于堆栈的根节点，此项留空。父拉取请求合并后仍会保持引用，直到子项被重新指定目标或重新设置父项。

pullRequest.stack.parentPullRequest.id string

不可变的 Origin 变更 ID。

pullRequest.stack.parentPullRequest.number string

pullRequest.stack.parentPullRequest.repository 对象

此 PR 的代码仓库引用。

pullRequest.stack.parentPullRequest.repository.id string

pullRequest.stack.parentPullRequest.repository.name string

pullRequest.stack.parentPullRequest.repository.owner 对象

仓库的所有者。

pullRequest.stack.parentPullRequest.repository.owner.slug string

所有者的唯一 URL 友好名称。

pullRequest.stack.parentPullRequest.repository.owner.id string

所有者命名空间的唯一 ID。

pullRequest.stack.parentPullRequest.repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

pullRequest.version object

该 PR 的最新版本。

pullRequest.version.number string

更改内的单调版本号 (从 1 开始) 。

pullRequest.version.headSha string

此版本的主提交 SHA。

pullRequest.version.baseSha string

此版本进行差异比较所依据的基准提交 SHA：记录此版本时解析出的基准分支最新提交。在下次推送 head 或重新指定目标之前，它可能落后于该分支当前的最新提交。

pullRequest.version.createdAt string

此版本的创建时间。RFC 3339 时间戳。

pullRequest.version.potentialMergeCommit object

Origin 针对此版本进行的测试合并，以及其准备进度 (state)。此版本对应的合并提交：其第二个父提交为 head_sha；第一个父提交为测试合并的 base_sha，即准备时基础分支的最新提交，该提交可能比此版本的 base_sha 更新。pull/\<number>/merge 引用仅指向最新版本的提交；较早的提交仍可通过 API (GetCommit) 按 SHA 读取，但无法通过 git 按 SHA 获取。此字段不同于 PullRequest.merge_commit_sha，后者仅在合并后设置。此字段设置在 PullRequest.version 和 PullRequestWebhook.version 上。

pullRequest.version.potentialMergeCommit.state string

此版本的准备进度；新版本在其准备工作完成前，状态为 unknown。无法识别的值必须视为 unknown。取值为 unknown、prepared、merge_conflict 之一。

pullRequest.version.potentialMergeCommit.sha string

仅当 state 为 prepared 时设置：这是一个有两个父提交的测试合并提交，第二个父提交是该版本的 head_sha，第一个父提交是 base_sha；当此版本为最新版本时，它是 pull/\<number>/merge 指向的提交；此后仍可通过 SHA 读取。

pullRequest.version.potentialMergeCommit.baseSha string

仅当 state 为 prepared 时设置：记录准备时基准分支的最新提交；可能比该版本的 base_sha 更新；如果只是基准分支向前推进，则不会刷新；重新打开时会重新准备。

repository object

该拉取请求所属的代码仓库。

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 之一。

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": "add-telemetry-schema",      "sha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"    },    "author": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "[email protected]"      }    },    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T14:45:00Z",    "additions": 128,    "deletions": 46,    "changedFiles": 5,    "stack": {      "id": "stk_01k2ja2000e0080000000000s1",      "parentPullRequest": {        "id": "pr_01k2ja2000e0080000000000d3",        "number": "16",        "repository": {          "id": "repo_01k2ja2000e0080000000000q4",          "name": "rocket",          "owner": {            "slug": "acme",            "id": "ns_01k2ja2000e0080000000000p3",            "type": "team"          }        }      }    },    "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.label.addedpull_request.label.removed

PR 所分配标签的变更。可通过 ListPullRequestLabels 读取当前标签集合。

负载字段

pullRequest 对象

所分配标签发生变更的 PR。

pullRequest.id string

不可变源站变更 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

所有者命名空间的唯一 ID。

pullRequest.repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

label 对象

该事件对应的标签。

label.id string

label.name string

label.color string

不含前导 # 的六位十六进制颜色值。

label.description string

actor object

添加或移除该标签的主体 (如果已知) 。

actor.user 对象

actor.user.id string

actor.user.email string 必填

actor.user.displayName string

便于阅读的显示名称：账户的名与姓，各自去除首尾空白后以空格连接，与产品 UI 中显示的名称完全一致。账户没有姓名时省略该字段；绝不会由电子邮件、id 或其他任何字段拼凑生成。对于无法解析出 actor 的 webhook 负载，该字段也可能不存在。

actor.user.handle string

用户已认领的个人资料句柄 (即 cursor.com /@handle 所对应的身份标识) ，不含 @ 前缀。仅当用户的个人资料公开可见时才会返回；未认领句柄的用户以及非公开个人资料将省略该字段。

actor.user.performedVia 对象

当应用使用安装用户令牌代表该用户执行此 actor 字段所描述的操作时，设置此字段。例如，对于评论作者，此字段指明创建该评论的应用，而非后来编辑或删除该评论的参与者。用户直接执行操作时，此字段不存在；委托数据不可用时，此字段也可能不存在。

actor.user.performedVia.app 对象

代表该用户执行操作的应用。

actor.user.performedVia.app.id string

actor.user.performedVia.app.displayName string

应用已注册的显示名称，存在时必不为空。若负载所属应用无法解析，或对于第一方 Cherri Code 门面 actor，则省略该字段。

actor.app object

actor.app.id string

actor.app.displayName string

应用已注册的显示名称，存在时必不为空。若负载所属应用无法解析，或对于第一方 Cherri Code 门面 actor，则省略该字段。

actor.serviceAccount 对象

actor.serviceAccount.id string

event.payload 示例：

{  "pullRequest": {    "id": "pr_01k2ja2000e0080000000000d4",    "number": "17",    "repository": {      "id": "repo_01k2ja2000e0080000000000q4",      "name": "rocket",      "owner": {        "slug": "acme",        "id": "ns_01k2ja2000e0080000000000p3",        "type": "team"      }    }  },  "label": {    "id": "lbl_01k2ja2000e0080000000000m1",    "name": "bug",    "color": "d73a4a",    "description": "Something isn't working"  },  "actor": {    "user": {      "id": "user_01k2ja2000e0080000000000c3",      "email": "[email protected]"    }  }}

拉取请求评论

EVENTpull_request.comment.created

在拉取请求上创建的评论。随评审一同提交的评论会在评审提交时发送，每条评论对应一个事件。

负载字段

pullRequest object

该评论所在的拉取请求。

pullRequest.id string

不可变的源变更 ID。

pullRequest.number string

pullRequest.repository 对象

此拉取请求所属代码仓库的引用。

pullRequest.repository.id string

pullRequest.repository.name string

pullRequest.repository.owner object

仓库的所有者。

pullRequest.repository.owner.slug string

所有者的唯一 URL 友好名称。

pullRequest.repository.owner.id string

所有者命名空间的唯一 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 对象

此讨论串所针对的拉取请求版本，包括其 head 和 base SHA (参见 PullRequestReview.pull_request_version) 。

comment.thread.version.number string

拉取请求内单调递增的版本编号 (从 1 开始) 。

comment.thread.version.headSha string

该版本的头部提交 SHA。

comment.thread.version.baseSha string

此版本用于比较差异的基准提交 SHA。

comment.thread.path string

该线程 diff 锚点所在的文件路径。普通讨论线程为空。

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 格式的时间戳。

comment.thread.updatedAt string

RFC 3339 格式的时间戳。

comment.body string

comment.author object

执行了外部可见操作的用户、应用或服务帐户。

comment.author.user object

comment.author.user.id string

comment.author.user.email string 必填

comment.author.user.displayName string

便于人类阅读的显示名称：账户的名和姓各自去除首尾空格后以空格连接——与产品 UI 呈现的名称完全一致。账户没有姓名时将省略；绝不会由电子邮件、ID 或任何其他字段合成。对于无法解析出操作者的 webhook 负载，该字段也可能不存在。

comment.author.user.handle string

用户已认领的个人资料用户名 (cursor.com /@handle 背后的身份标识) ，不含 @ 前缀。仅当用户的个人资料公开可见时才会显示；未认领用户名的用户以及非公开个人资料不会显示该字段。

comment.author.user.performedVia object

当应用使用安装用户 token 代表该用户执行此 actor 字段所描述的操作时，会设置此字段。例如，对于评论的作者，该字段表示创建该评论的应用，而非之后编辑或删除该评论的 actor。用户直接执行操作时不包含此字段；委托数据不可用时也可能不包含。

comment.author.user.performedVia.app object

代表用户执行操作的应用。

comment.author.user.performedVia.app.id string

comment.author.user.performedVia.app.displayName string

应用注册的显示名称；如果存在，则绝不会为空。对于无法解析所属应用的负载，以及第一方 Cherri Code 门面 actor，均省略此字段。

comment.author.app 对象

comment.author.app.id string

comment.author.app.displayName string

应用注册的显示名称；如果存在，则绝不会为空。对于无法解析所属应用的负载，以及第一方 Cherri Code 门面 actor，均省略此字段。

comment.author.serviceAccount 对象

comment.author.serviceAccount.id string

comment.createdAt string

RFC 3339 格式的时间戳。

comment.updatedAt 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"      }    }  },  "comment": {    "id": "cmt_01k2ja2000e0080000000000e5",    "thread": {      "id": "cth_01k2ja2000e0080000000000s6",      "version": {        "number": "3",        "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",        "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"      },      "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": "[email protected]"      }    },    "createdAt": "2026-08-01T09:30:00Z",    "updatedAt": "2026-08-02T14:45:00Z"  }}

拉取请求评论表情回应事件

EVENTpull_request.comment.reaction.addedpull_request.comment.reaction.removed

在拉取请求评论上添加或移除表情回应。信封的 event.type 表示该操作。添加操作至少会送达一次：如果回应者在评论上再次添加已有的回应，则会针对相同的 (comment, reactor, content) 再次送达 pull_request.comment.reaction.added；如果移除回应者并未添加的回应，则不会送达任何事件。

负载字段

pullRequest object

该评论所在的 PR。

pullRequest.id string

不可变的源更改 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

所有者命名空间的唯一 ID。

pullRequest.repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

comment object

该回应所针对的评论。

comment.id string

comment.thread 对象

该评论所属的线程。

comment.thread.id string

reaction 对象

被添加或移除的表态。

reaction.content string

对该评论添加的反应。取值集合是封闭的；无法识别的值应视为接收方无法渲染的反应。取值为 thumbs_up、thumbs_down、laugh、hooray、confused、heart、rocket、eyes 之一。

reaction.reactor 对象

添加该表情回应的 principal。只有回应者本人能移除它，因此在 added 和 removed 事件中，执行操作的都是该 principal。

reaction.reactor.user 对象

reaction.reactor.user.id string

reaction.reactor.user.email string 必填

reaction.reactor.user.displayName string

便于人类阅读的显示名称：账户的名与姓各自去除首尾空格后以空格连接——与产品 UI 中呈现的名称完全一致。账户没有姓名时将省略；绝不会由电子邮件、id 或其他任何字段合成。对于无法解析出 actor 的 webhook 负载，该字段也可能不存在。

reaction.reactor.user.handle string

用户已认领的个人资料 handle (cursor.com /@handle 所对应的身份标识) ，不含 @ 前缀。仅在用户的个人资料公开可见时出现；未认领 handle 的用户以及非公开个人资料将省略该字段。

reaction.reactor.user.performedVia 对象

当应用使用安装用户令牌代表此用户执行此执行者字段所描述的操作时，会设置此字段。例如，对于评论的作者，此字段指明创建该评论的应用，而不是后来编辑或删除评论的执行者。用户直接执行操作时，此字段不存在；委托数据不可用时，此字段也可能不存在。

reaction.reactor.user.performedVia.app object

代表用户执行操作的应用。

reaction.reactor.user.performedVia.app.id string

reaction.reactor.user.performedVia.app.displayName string

应用注册的显示名称，存在时必不为空。若负载所属的应用无法解析，或为第一方 Cherri Code 门面 actor，则会省略该字段。

reaction.reactor.app 对象

reaction.reactor.app.id string

reaction.reactor.app.displayName string

应用注册的显示名称，存在时必不为空。若负载所属的应用无法解析，或为第一方 Cherri Code 门面 actor，则会省略该字段。

reaction.reactor.serviceAccount 对象

reaction.reactor.serviceAccount.id string

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"    }  },  "reaction": {    "content": "thumbs_up",    "reactor": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "[email protected]"      }    }  }}

拉取请求评审事件

EVENTpull_request.review.submittedpull_request.review.dismissed

负载字段

pullRequest 对象

该评审所针对的 PR。

pullRequest.id string

不可变的 Origin 更改 ID。

pullRequest.number string

pullRequest.repository 对象

此拉取请求的代码仓库引用。

pullRequest.repository.id string

pullRequest.repository.name string

pullRequest.repository.owner 对象

仓库的所有者。

pullRequest.repository.owner.slug string

所有者的唯一 URL 友好名称。

pullRequest.repository.owner.id string

所有者命名空间的唯一 ID。

pullRequest.repository.owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

review 对象

已提交或已驳回的评审。驳回时会设置 review.dismissal。

review.id string

稳定来源评审标识符。

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

用户已认领的个人资料账号名 (cursor.com /@handle 背后的身份标识) ，不含 @ 前缀。仅当用户的个人资料处于公开可见状态时才会显示；未认领账号名的用户以及非公开个人资料不会显示该字段。

review.author.user.performedVia 对象

当应用使用安装用户 token 代表该用户执行此操作者字段所描述的操作时，会设置此字段。例如，在评论的作者字段中，它表示创建该评论的应用，而不是之后编辑或删除该评论的操作者。用户直接执行操作时此字段不存在；委托数据不可用时也可能不存在。

review.author.user.performedVia.app 对象

代表用户执行操作的应用。

review.author.user.performedVia.app.id string

review.author.user.performedVia.app.displayName string

应用注册的显示名称，存在时绝不为空。若负载所属应用无法解析，或该负载来自第一方 Cherri Code 外观层参与者，则会省略此字段。

review.author.app 对象

review.author.app.id string

review.author.app.displayName string

应用注册的显示名称，存在时绝不为空。若负载所属应用无法解析，或该负载来自第一方 Cherri Code 外观层参与者，则会省略此字段。

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

拉取请求中的单调递增版本号 (从 1 开始) 。

review.pullRequestVersion.headSha string

此版本的头部提交 SHA。

review.pullRequestVersion.baseSha string

此版本进行差异比较时所依据的基准提交 SHA。

review.dismissal 对象

评审被撤销后即设置该值；当该结论仍计入拉取请求的评审状态时，此字段不存在。

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

用户已认领的个人资料账号名 (cursor.com /@handle 背后的身份标识) ，不含 @ 前缀。仅当用户的个人资料处于公开可见状态时才会显示；未认领账号名的用户以及非公开个人资料不会显示该字段。

review.dismissal.dismissedBy.user.performedVia 对象

当应用使用安装用户 token 代表该用户执行此操作者字段所描述的操作时，会设置此字段。例如，在评论的作者字段中，它指明创建该评论的应用，而非之后编辑或删除该评论的操作者。若用户直接执行操作，则此字段不存在；委托数据不可用时，此字段也可能不存在。

review.dismissal.dismissedBy.user.performedVia.app 对象

代表用户执行操作的应用。

review.dismissal.dismissedBy.user.performedVia.app.id string

review.dismissal.dismissedBy.user.performedVia.app.displayName string

应用注册的显示名称，存在时绝不为空。若负载所属应用无法解析，或该负载来自第一方 Cherri Code 外观层参与者，则会省略此字段。

review.dismissal.dismissedBy.app 对象

review.dismissal.dismissedBy.app.id string

review.dismissal.dismissedBy.app.displayName string

应用注册的显示名称，存在时绝不为空。若负载所属应用无法解析，或该负载来自第一方 Cherri Code 外观层参与者，则会省略此字段。

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": "[email protected]"      }    },    "verdict": "approve",    "body": "Approving. The telemetry schema matches the spec.",    "submittedAt": "2026-08-02T15:00:00Z",    "pullRequestVersion": {      "number": "3",      "headSha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",      "baseSha": "3b1f9c2d8a7e6f5049c8b7a6d5e4f3a2b1c0d9e8"    }  }}

拉取请求审阅人事件

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

用户已认领的个人资料用户名 (即 cursor.com /@handle 背后对应的身份) ，不含 @ 前缀。仅当用户的个人资料公开可见时才会显示；未认领用户名的用户以及非公开个人资料将省略此字段。

reviewer.user.performedVia 对象

当应用使用安装用户令牌代表此用户执行此 actor 字段所描述的操作时设置此字段。例如，对于评论的作者，此字段指明创建该评论的应用，而不是之后编辑或删除评论的操作者。用户直接执行操作时不设置此字段；委托数据不可用时也可能不设置。

reviewer.user.performedVia.app 对象

代表用户执行操作的应用。

reviewer.user.performedVia.app.id string

reviewer.user.performedVia.app.displayName string

应用注册的显示名称，存在时必定非空。对于无法解析出应用的负载，以及第一方 Cherri Code 门面 actor，此字段会被省略。

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

用户已认领的个人资料用户名 (即 cursor.com /@handle 背后对应的身份) ，不含 @ 前缀。仅当用户的个人资料公开可见时才会出现；未认领用户名的用户及非公开个人资料均不显示。

createdBy.user.performedVia 对象

当某个应用使用 installation user token 代表此用户执行该 actor 字段所描述的操作时，会设置此字段。例如，对于评论的作者，它标识的是创建该评论的应用，而非之后编辑或删除该评论的 actor。用户直接执行操作时，此字段不存在；委托数据不可用时，此字段也可能不存在。

createdBy.user.performedVia.app 对象

代表该用户执行操作的应用。

createdBy.user.performedVia.app.id string

createdBy.user.performedVia.app.displayName string

应用注册的显示名称；若存在，则必定非空。对于无法解析出应用的负载，以及第一方 Cherri Code 门面主体，此字段会被省略。

createdBy.app 对象

createdBy.app.id string

createdBy.app.displayName string

应用注册的显示名称，存在时必定非空。对于无法解析出应用的负载，以及第一方 Cherri Code 门面 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": "[email protected]"    }  },  "createdVia": "codeowners",  "createdAt": "2026-08-02T14:45:00Z"}

检查运行事件

EVENTrepository.check_run.createdrepository.check_run.updatedrepository.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 对象

该检查运行所属的套件。

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 所关联的已解析 head commit 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 必填

checkSuite.actor.user.displayName string

便于阅读的显示名称：账户的名和姓各自去除首尾空格后以空格连接而成，与产品 UI 中呈现的名称完全一致。账户没有姓名时省略；绝不会根据电子邮件、id 或其他任何字段拼凑生成。若 webhook 负载中的操作者无法解析，该字段也可能不存在。

checkSuite.actor.user.handle string

用户已认领的个人资料用户名柄 (即 cursor.com /@handle 背后的身份标识) ，不含 @ 前缀。仅当用户的个人资料公开可见时才会显示；未认领用户名柄的用户和非公开个人资料均不会显示此字段。

checkSuite.actor.user.performedVia 对象

当应用使用安装用户令牌代表此用户执行此操作者字段所描述的操作时设置此字段。例如，对于评论作者，此字段指明创建该评论的应用，而不是后来编辑或删除该评论的操作者。用户直接执行操作时不设置此字段；委托数据不可用时也可能不设置。

checkSuite.actor.user.performedVia.app 对象

代表用户执行操作的应用。

checkSuite.actor.user.performedVia.app.id string

checkSuite.actor.user.performedVia.app.displayName string

应用已注册的显示名称；如果存在，则绝不会为空。对于无法解析其应用的负载，以及第一方 Cherri Code 门面 actor，省略此字段。

checkSuite.actor.app 对象

checkSuite.actor.app.id string

checkSuite.actor.app.displayName string

应用注册的显示名称，存在时绝不为空。在应用无法解析的负载以及第一方 Cherri Code 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 对象

此检查运行所属的套件。

checkRun.checkSuite.id string

checkRun.sha string

该 check run 所关联的已解析 head 提交 SHA (小写十六进制) 。

checkRun.key string

由应用为该检查运行指定的幂等键。

checkRun.name string

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

checkRun.status string

生命周期状态。failing 表示某次运行仍在进行，但所属应用已确定它无法通过：对于门禁和必需检查仍处于待处理状态，尚无 conclusion，可向读取方发出预警。rerequested 表示某次运行已完成，且已请求重新运行，但所属应用尚未响应：对读取方而言处于待处理状态 (呈现方式类似 queued) ，conclusion 和耗时仍描述被取代的那次尝试。仅由 Origin 在重新请求时 (RerequestCheckRun) 设置；应用无法发布此状态。取值为 queued、in_progress、completed、rerequested、failing 之一。

checkRun.conclusion string

仅当 status 为 completed 或 rerequested 时存在。对于 rerequested 的运行，它表示已被取代的尝试的裁决：应将该运行视为待处理，仅当 status == completed 时读取 conclusion。可能的值为 success、failure、neutral、cancelled、skipped、timed_out、action_required 或 stale。

checkRun.detailsUrl string

指向有关此特定检查运行的更多详细信息的链接 (如果已设置) 。

checkRun.externalUpdatedAt string

外部系统的最后更新时间，用于排序。RFC 3339 时间戳。

checkRun.startedAt string

检查运行开始的时间 (如有报告) 。RFC 3339 时间戳。

checkRun.completedAt string

检查运行完成的时间 (如有报告) 。RFC 3339 时间戳。

checkRun.createdAt string

RFC 3339 格式的时间戳。

checkRun.updatedAt string

Origin 上次写入该运行的时间。如果某次提交因过时而被忽略，或重复了已存储的值 (参见 PostCheckRunResponse.outcome) ，则此时间不会更新，因此无法区分这两种情况。RFC 3339 时间戳。

checkRun.externalId string

由提供者为此次检查尝试分配的不可变标识 (参见 CheckRunInput.external_id：建议每次执行使用一个) 。

checkRun.actor object

生成该 check run 的主体；始终是所属套件的 actor。

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.user.performedVia 对象

当应用使用安装用户令牌代表此用户执行此操作者字段所描述的操作时，才会设置此字段。例如，对于评论的作者，此字段指明创建该评论的应用，而不是后来编辑或删除该评论的操作者。用户直接执行操作时不设置此字段；委托数据不可用时也可能不设置。

checkRun.actor.user.performedVia.app 对象

代表用户执行操作的应用。

checkRun.actor.user.performedVia.app.id string

checkRun.actor.user.performedVia.app.displayName string

应用已注册的显示名称；若存在则绝不会为空。对于无法解析应用的负载，以及第一方 Cherri Code 门面 actor，省略此字段。

checkRun.actor.app 对象

checkRun.actor.app.id string

checkRun.actor.app.displayName string

应用注册的显示名称，存在时绝不为空。在应用无法解析的负载以及第一方 Cherri Code 门面执行者上会被省略。

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

可选的截止时间。省略或未设置表示不会过期。运行完成时会清除该值，包括运行到期并变为 timed_out 的情况 (参见 CheckRunInput.deadline_at) 。RFC 3339 时间戳。

checkRun.isRerequestable boolean

报告应用是否将此运行声明为可重新请求 (CheckRunInput.is_rerequestable)。

checkRun.rerequestedAt string

重新请求待处理期间，此字段会被设置；提供者再次发布时则会清除。未设置表示没有待处理的重新请求。设置期间，status 为 rerequested，该运行在此提交的 CI 状态中仍为 pending (conclusion 和时间信息沿用已被取代的结果) ；所属应用会发布其通过声明 is_rerequestable 所承诺的运行来作出响应——可以是具有相同 key 的新运行，也可以是对此运行的更新 (这会清除此字段) ——之后便可再次请求该运行。RFC 3339 时间戳。

checkRun.rerequestedBy 对象

重新请求该 run 的主体。仅当设置了 rerequested_at 时存在；所属应用响应时会与其一并清除。

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

用户已认领的个人资料用户名 (即 cursor.com /@handle 背后的身份标识) ，不含 @ 前缀。仅当用户的个人资料公开可见时才会显示；未认领用户名的用户和非公开个人资料均不显示此字段。

checkRun.rerequestedBy.user.performedVia 对象

当应用使用安装用户令牌代表此用户执行此操作者字段所描述的操作时设置此字段。例如，对于评论的作者，此字段指明创建该评论的应用，而不是后来编辑或删除该评论的操作者。用户直接执行操作时不设置此字段；委托数据不可用时也可能不设置。

checkRun.rerequestedBy.user.performedVia.app 对象

代表用户执行操作的应用。

checkRun.rerequestedBy.user.performedVia.app.id string

checkRun.rerequestedBy.user.performedVia.app.displayName string

应用注册的显示名称，存在时绝不为空。在应用无法解析的负载以及第一方 Cherri Code facade actor 上会被省略。

checkRun.rerequestedBy.app 对象

checkRun.rerequestedBy.app.id string

checkRun.rerequestedBy.app.displayName string

应用注册的显示名称，存在时绝不为空。在应用无法解析的负载以及第一方 Cherri Code 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-02T14:45:00Z",    "externalId": "build-8842",    "actor": {      "user": {        "id": "user_01k2ja2000e0080000000000c3",        "email": "[email protected]"      }    }  },  "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": "[email protected]"      }    },    "output": {      "title": "Unit tests",      "summary": "128 tests passed.",      "text": "All suites green."    }  }}

已请求重新运行检查

EVENTrepository.check_run.rerequested

repository.check_run.rerequested webhook 负载，仅投递给拥有该 check run 的应用。要响应此请求，请针对相同的 head SHA 和 key 提交一个新的 run——可以是全新的 run (新的 external_id) ，也可以更新被重新请求的 run。在响应请求的提交清除 rerequested_at 之前，该 run 会显示 status: rerequested (其 conclusion 和时间信息仍是已被取代的结果) 。每次被接受的重新请求都会产生一个事件；run 在得到响应后可以再次被请求，因此只需根据事件 id 对重复投递去重；check_run.rerequested_at 记录尚未处理的请求标记。负载不包含拉取请求上下文 (check runs 关联到 (repository, sha)) ：需要拉取请求信息的消费者可通过自身的 head 映射，根据 check_run.sha 查找对应的拉取请求，或使用 ListPullRequests 并筛选出其构建所针对的 head 分支。

负载字段

repository 对象

该检查运行所属的仓库。

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 对象

该检查运行所属的套件。

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

测试套件所关联的已解析头部提交 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 必填

checkSuite.actor.user.displayName string

便于阅读的显示名称：账户的名和姓各自去除首尾空格后以空格连接而成——与产品 UI 呈现的名称完全一致。账户没有姓名时省略；绝不会根据电子邮件、id 或其他任何字段拼凑生成。若 webhook 负载中的操作者无法解析，该字段也可能不存在。

checkSuite.actor.user.handle string

用户已认领的个人资料 handle (即 cursor.com /@handle 背后的身份标识) ，不含 @ 前缀。仅当用户的个人资料公开可见时才会显示；未认领 handle 的用户以及非公开个人资料均不显示该字段。

checkSuite.actor.user.performedVia 对象

当应用使用安装用户令牌代表该用户执行此操作者字段所描述的操作时，会设置该字段。例如，对于评论的作者，该字段指明的是创建评论的应用，而非后来编辑或删除评论的操作者。用户直接执行操作时不包含该字段；委托数据不可用时也可能不包含。

checkSuite.actor.user.performedVia.app 对象

代表用户执行操作的应用。

checkSuite.actor.user.performedVia.app.id string

checkSuite.actor.user.performedVia.app.displayName string

应用注册的显示名称，存在时不会为空。若负载对应的应用无法解析，或对于第一方 Cherri Code 门面 actor，则省略该字段。

checkSuite.actor.app 对象

checkSuite.actor.app.id string

checkSuite.actor.app.displayName string

应用注册的显示名称，存在时不会为空。若负载对应的应用无法解析，或对于第一方 Cherri Code 门面 actor，则省略该字段。

checkSuite.actor.serviceAccount 对象

checkSuite.actor.serviceAccount.id string

checkRun object

被重新请求的检查运行 (status: rerequested) ；check_run.rerequested_at 记录时间戳，check_run.rerequested_by 记录发起请求的主体。

checkRun.id string

由服务器分配的检查运行唯一 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 对象

此检查运行所属的套件。

checkRun.checkSuite.id string

checkRun.sha string

此检查运行所关联的已解析头部提交 SHA (小写十六进制) 。

checkRun.key string

由应用为该检查运行指定的幂等键。

checkRun.name string

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

checkRun.status string

生命周期状态。failing 表示运行仍在进行中，但所属应用已确定它无法通过：对于关卡和必需检查仍处于待处理状态，尚无 conclusion，可向读取方提前发出警告。rerequested 表示某次已完成的运行已被请求重新运行，但所属应用尚未响应：对读取方而言处于待处理状态 (渲染方式与 queued 相同) ，且 conclusion 和各项时间仍描述已被取代的那次尝试。仅在重新请求时由 Origin 设置 (RerequestCheckRun) ；应用无法设置此状态。取值为 queued、in_progress、completed、rerequested、failing 之一。

checkRun.conclusion string

仅当 status 为 completed 或 rerequested 时存在。对于 rerequested 的运行，它表示被取代尝试的判定：应将该运行视为待处理，仅在 status == completed 时读取 conclusion。取值为 success、failure、neutral、cancelled、skipped、timed_out、action_required、stale 之一。

checkRun.detailsUrl string

指向此特定检查运行更多详细信息的链接 (如果已设置) 。

checkRun.externalUpdatedAt string

外部系统的最后更新时间，用于排序。RFC 3339 时间戳。

checkRun.startedAt string

检查运行开始的时间 (如有报告) 。RFC 3339 时间戳。

checkRun.completedAt string

检查运行完成的时间 (如果有报告) 。RFC 3339 时间戳。

checkRun.createdAt string

RFC 3339 格式的时间戳。

checkRun.updatedAt string

Origin 上次写入此运行的时间。对于因过时而被忽略的提交，或重复已存储值的提交，该时间不会更新 (参见 PostCheckRunResponse.outcome) ，因此无法区分这两种情况。RFC 3339 时间戳。

checkRun.externalId string

由提供方为此检查尝试分配的不可变标识 (参见 CheckRunInput.external_id：建议每次执行使用一个) 。

checkRun.actor object

生成该 check run 的主体；始终是所属 suite 的 actor。

checkRun.actor.user 对象

checkRun.actor.user.id string

checkRun.actor.user.email 字符串 必填

checkRun.actor.user.displayName string

便于阅读的显示名称：账户的名和姓各自去除首尾空格后以空格连接而成——与产品 UI 呈现的名称完全一致。账户没有姓名时省略；绝不会根据电子邮件、id 或其他任何字段拼凑生成。若 webhook 负载中的操作者无法解析，该字段也可能不存在。

checkRun.actor.user.handle string

用户已认领的个人资料句柄 (即 cursor.com /@handle 背后的身份标识) ，不含 @ 前缀。仅当用户的个人资料公开可见时才会显示；未认领句柄的用户以及非公开个人资料均不显示该字段。

checkRun.actor.user.performedVia 对象

当应用使用安装用户 token 代表该用户执行此 actor 字段所描述的操作时，设置该字段。例如，对于评论的作者，该字段指明的是创建评论的应用，而非后来编辑或删除评论的操作者。用户直接执行操作时不包含该字段；委托数据不可用时也可能不包含。

checkRun.actor.user.performedVia.app 对象

代表用户执行操作的应用。

checkRun.actor.user.performedVia.app.id string

checkRun.actor.user.performedVia.app.displayName string

应用注册的显示名称，存在时不会为空。若负载对应的应用无法解析，或对于第一方 Cherri Code 门面 actor，则省略该字段。

checkRun.actor.app 对象

checkRun.actor.app.id string

checkRun.actor.app.displayName string

应用注册的显示名称，存在时不会为空。若负载对应的应用无法解析，或对于第一方 Cherri Code 门面 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

可选截止时间。省略或未设置表示永不过期。运行完成时会清除，包括运行因 timed_out 而过期的情况 (参见 CheckRunInput.deadline_at) 。RFC 3339 时间戳。

checkRun.isRerequestable boolean

上报该运行的应用是否声明此运行可重新请求 (CheckRunInput.is_rerequestable)。

checkRun.rerequestedAt string

重新请求待处理时设置；提供者再次发布时清除。未设置表示没有待处理的重新请求。设置期间，status 为 rerequested，该运行在提交的 CI 状态中仍为 pending (conclusion 和计时信息沿用被取代的结果) ；所属应用通过发布其承诺提交的运行并声明 is_rerequestable 来响应——可以是具有相同 key 的新运行，也可以是对该运行的更新 (这会清除此字段) 。此后，该运行可以再次被重新请求。RFC 3339 时间戳。

checkRun.rerequestedBy 对象

重新请求该运行的主体。仅当 rerequested_at 已设置时存在；在所属应用响应时会与其一并被清除。

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.user.performedVia 对象

当应用使用安装用户令牌代表该用户执行此操作者字段所描述的操作时，设置该字段。例如，对于评论的作者，该字段指明的是创建评论的应用，而非后来编辑或删除评论的操作者。用户直接执行操作时不包含该字段；委托数据不可用时也可能不包含。

checkRun.rerequestedBy.user.performedVia.app 对象

代表用户执行操作的应用。

checkRun.rerequestedBy.user.performedVia.app.id string

checkRun.rerequestedBy.user.performedVia.app.displayName string

应用注册的显示名称，存在时不会为空。若负载对应的应用无法解析，或对于第一方 Cherri Code 门面 actor，则省略该字段。

checkRun.rerequestedBy.app 对象

checkRun.rerequestedBy.app.id string

checkRun.rerequestedBy.app.displayName string

应用注册的显示名称，存在时不会为空。若负载对应的应用无法解析，或对于第一方 Cherri Code 门面 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": "[email protected]"      }    }  },  "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": "[email protected]"      }    },    "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": "[email protected]"      }    }  }}

安装已创建

EVENTinstallation.created

负载字段

installation 对象

事件发生时的安装快照。

installation.id string

installation.appId string

已安装应用的标识符；与负载中的 app.id 取值相同。

installation.target 对象

仓库的所有者。

installation.target.slug string

所有者的唯一 URL 友好名称。

installation.target.id string

所有者命名空间的唯一 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 格式的时间戳。

installation.deletedAt string

RFC 3339 格式的时间戳。

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

用户已认领的个人资料用户名 (即 cursor.com /@handle 背后的身份标识) ，不含 @ 前缀。仅当用户的个人资料公开可见时才会提供；未认领用户名的用户以及个人资料非公开的用户不会提供此字段。

installation.installedBy.performedVia 对象

当应用使用 installation user token 代表该用户执行此操作者字段所描述的操作时，会设置该字段。例如，对于评论的作者，该字段指明创建该评论的应用，而非之后编辑或删除该评论的操作者。若用户直接执行操作，则不存在该字段；若委托数据不可用，该字段也可能不存在。

installation.installedBy.performedVia.app 对象

代表用户执行操作的应用。

installation.installedBy.performedVia.app.id string

installation.installedBy.performedVia.app.displayName string

应用注册的显示名称，存在时绝不为空。若负载中的应用无法解析，或操作者为第一方 Cherri Code 门面身份，则省略此字段。

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": "[email protected]"    }  },  "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

所有者命名空间的唯一 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 格式的时间戳。

installation.updatedAt string

RFC 3339 时间戳。

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 的用户以及非公开个人资料不会显示此字段。

installation.installedBy.performedVia 对象

当应用使用 installation user token 代表该用户执行此操作者字段所描述的操作时，会设置此字段。例如，在评论的作者字段中，它标明的是创建该评论的应用，而非之后编辑或删除该评论的操作者。用户直接执行操作时不存在该字段；委托数据不可用时也可能不存在。

installation.installedBy.performedVia.app object

代表用户执行操作的应用。

installation.installedBy.performedVia.app.id string

installation.installedBy.performedVia.app.displayName string

应用注册的显示名称；只要存在，就绝不会为空。对于无法解析应用的负载，以及第一方 Cherri Code 门面角色，均省略此字段。

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": "[email protected]"    }  },  "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

所属命名空间的唯一 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

所有者命名空间的唯一 ID。

installation.repositories[].owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

installation.scopes 数组

installation.repositoriesCount integer

实际总数；当 repository_selection 为 "all" 时为 0。

installation.createdAt string

RFC 3339 时间戳。

installation.updatedAt string

RFC 3339 时间戳。

installation.deletedAt string

RFC 3339 时间戳。

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 的用户以及非公开个人资料会省略该字段。

installation.installedBy.performedVia 对象

如果应用使用安装用户令牌代表该用户执行了此 actor 字段所描述的操作，则设置该字段。例如，如果该字段位于评论作者信息中，它指的是创建评论的应用，而不是之后编辑或删除评论的操作者。用户直接执行操作时不包含该字段；委托数据不可用时也可能不包含该字段。

installation.installedBy.performedVia.app object

代表用户执行操作的应用。

installation.installedBy.performedVia.app.id string

installation.installedBy.performedVia.app.displayName string

应用注册的显示名称，存在时绝不为空。若负载中的应用无法解析，或操作者为第一方 Cherri Code 门面，则省略此字段。

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": "[email protected]"    },    "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

所属命名空间的唯一 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

所属命名空间的唯一 ID。

installation.repositories[].owner.type string

team 或 user。仅输出；未知时不设置。取值为 team、user 之一。

installation.scopes 数组

installation.repositoriesCount integer

实际总数；当 repository_selection 为 "all" 时为 0。

installation.createdAt string

RFC 3339 格式的时间戳。

installation.updatedAt string

RFC 3339 格式的 timestamp。

installation.deletedAt string

RFC 3339 时间戳。

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 的用户和非公开个人资料不会显示该字段。

installation.installedBy.performedVia object

当应用使用安装用户令牌代表该用户执行此 actor 字段所描述的操作时，会设置该字段。例如，对于评论的作者，该字段标识创建评论的应用，而不是后来编辑或删除评论的操作者。用户直接操作时不包含该字段；委托数据不可用时也可能不包含。

installation.installedBy.performedVia.app object

代表用户执行操作的应用。

installation.installedBy.performedVia.app.id string

installation.installedBy.performedVia.app.displayName string

应用注册的显示名称，在存在时绝不会为空。对于无法解析应用的负载，以及第一方 Cherri Code 门面操作者，均省略此字段。

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": "[email protected]"    }  },  "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

所有者命名空间的唯一 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 时间戳。

installation.deletedAt string

RFC 3339 时间戳。

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 的用户以及非公开个人资料会省略该字段。

installation.installedBy.performedVia 对象

当应用使用安装用户令牌代表此用户执行此操作者字段所描述的操作时设置。例如，在评论作者字段中，它指明创建评论的应用，而不是后来编辑或删除评论的操作者。用户直接执行操作时此字段为空；委托数据不可用时也可能为空。

installation.installedBy.performedVia.app 对象

代表用户执行操作的应用。

installation.installedBy.performedVia.app.id string

installation.installedBy.performedVia.app.displayName string

应用注册的显示名称，存在时绝不为空。若负载中的应用无法解析，或操作者是第一方 Cherri Code 的代理身份，则省略此字段。

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": "[email protected]"    },    "deletedAt": "2026-08-03T08:15:00Z"  },  "app": {    "id": "app_01k2ja2000e0080000000000a1",    "displayName": "CI Status Bot"  }}

检查运行注释

EVENTrepository.check_run.annotations.created

一次 CreateCheckRunAnnotations 请求向检查运行追加了注释 (repository.check_run.annotations.created) 。注释只能追加，不能单独编辑或删除，因此 .created 就是注释的整个生命周期；一次请求对应一个事件。check_run 是引用，不是快照：如需获取该检查运行的状态、结论和输出，请调用 GetCheckRun。annotations 按请求顺序排列；如果 Origin 为确保请求体能够正常投递而限制了列表长度，其条目数可能少于 annotations_count。可通过 ListCheckRunAnnotations 分页获取其余注释。与其他检查运行 Webhook 一样，负载不包含拉取请求上下文：可根据 sha 查找对应的拉取请求。

负载字段

repository 对象

该检查运行所属的代码仓库。

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。

checkRun object

追加了这些注释的检查运行及其所属套件。

checkRun.id string

checkRun.name string

checkRun.checkSuite 对象

该检查运行所属的套件。

checkRun.checkSuite.id string

sha string

与此检查运行关联的已解析 head 提交 SHA (小写十六进制) 。

annotations array

追加的注释，按请求顺序排列。当 Origin 限制了列表长度时，注释数量可能少于 annotations_count。

annotations[].id string

annotations[].checkRunId string

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 对象

check-run 注释的可选源代码位置。只要外层注释提供了此消息，就必须填写 path、start_line 和 end_line。path 为规范化路径，且相对于代码仓库根目录；行号和列号均为从 1 开始计数的正整数，且首尾均包含在内；columns 仅适用于单行范围。

annotations[].location.path string 必填

最大 UTF-8 大小：4096 字节。

annotations[].location.startLine integer 必填

annotations[].location.endLine 整数 必填

annotations[].location.columns 对象

可选的成对列，用于指定单行注释的范围。

annotations[].location.columns.startColumn integer

annotations[].location.columns.endColumn integer

annotationsCount integer

该请求追加的注释数量。

createdAt string

批处理被追加的时间。RFC 3339 格式的时间戳。

event.payload 示例：

{  "repository": {    "id": "repo_01k2ja2000e0080000000000q4",    "name": "rocket",    "owner": {      "slug": "acme",      "id": "ns_01k2ja2000e0080000000000p3",      "type": "team"    }  },  "checkRun": {    "id": "cr_01k2ja2000e0080000000000g7",    "name": "unit-tests",    "checkSuite": {      "id": "crg_01k2ja2000e0080000000000h8"    }  },  "sha": "9a41f0c3d2b8e7f6a5c4d3e2f1b0a9c8d7e6f5a4",  "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,        "columns": {          "startColumn": 5,          "endColumn": 31        }      }    },    {      "id": "cra_01k2ja2000e0080000000000v2",      "checkRunId": "cr_01k2ja2000e0080000000000g7",      "annotationLevel": "failure",      "message": "Three tests failed in telemetry.test.ts.",      "title": "Test failures",      "rawDetails": "FAIL telemetry.test.ts flushes on shutdown (expected 1 call, received 0)",      "createdAt": "2026-08-02T14:45:00Z",      "updatedAt": "2026-08-02T14:45:00Z"    }  ],  "annotationsCount": 2,  "createdAt": "2026-08-02T14:45:00Z"}