origin-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Origin API

The docs are the source of truth. Do not name an endpoint, scope, event slug, header, or limit from memory. Where this file and the docs disagree, the docs win.

The docs live under

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

llms.txt

is the index and links every section, endpoint, and webhook payload.

openapi.yaml

is the contract, and "Endpoint reference" explains its

x-origin-*

extensions.

llms-full.txt

is the whole reference in one file.

changelog

says what moved. For one question, start at

llms.txt

and fetch only the section that answers it.

llms-full.txt

and

openapi.yaml

are each several hundred kilobytes, too large to read into context whole. When you need all of them, as a porting brief does, save them locally if you can, outside any repository you are working in, search them for the section heading or annotation you need, and read only the matching part. Cite

operationId

s and section names.

文档是唯一事实来源。不要凭记忆说出任何 endpoint、scope、event slug、header 或 limit。如果此文件与文档不一致，以文档为准。

文档位于

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

。

llms.txt

是 index，并链接每个 section、endpoint 和 webhook payload。

openapi.yaml

是 contract，"Endpoint reference" 介绍了其中的

x-origin-*

extensions。

llms-full.txt

将完整参考资料集中在一个文件中。

changelog

说明各项内容发生了什么变动。对于单个问题，应从

llms.txt

开始，并且只获取能够回答该问题的 section。

llms-full.txt

和

openapi.yaml

各自都有数百 KB，无法一次性完整读入 context。

如果确实需要全部文件，例如迁移简报需要这样做，应尽可能将它们保存在本地，放在当前正在处理的任何 repository 之外；按 section heading 或 annotation 搜索这些文件，并且只读取匹配的部分。引用

operationId

和 section 名称。

Rules to check first

首先检查的规则

Native or mirror. A repository is either native (created on Origin) or a GitHub mirror. On a native repository an installation has its full scopes and every write. On a GitHub mirror, every event except
```
repository.pushed
```
still arrives, every call beyond metadata and contents reads returns
```
403
```
, and merging a pull request or changing the default branch is not available ("Mirrored repositories", "Events").
Subscribe. Only
```
installation.*
```
events arrive without a subscription. A missing subscription produces silence, not an error ("Events").
Verify, dedupe, acknowledge. Verify the signature over the raw body before parsing, dedupe on the delivery ID, return
```
2xx
```
, then process ("Signature verification", "Retries", "Automatic disable"). Origin signs a digest, which Standard Webhooks does not, so a generic verifier fails.
Scopes from the spec. Request the union of
```
x-origin-scopes.scopes
```
over the operations the app calls ("Scopes").
Opaque tokens and IDs. Do not build or parse page tokens or IDs ("Pagination", "IDs").

One section name the index does not make obvious: what happens to a check-run post that arrives out of order is under "Ordering writes".

Porting an existing GitHub App: use

port-github-app-to-origin

in this plugin.

Native or mirror。 repository 要么是 native（在 Origin 上创建），要么是 GitHub mirror。在 native repository 中，installation 拥有完整 scopes 和所有 write 权限。在 GitHub mirror 中，除
```
repository.pushed
```
外的所有 event 仍会到达；超出 metadata 和 contents reads 的所有 call 都会返回
```
403
```
；merge pull request 或更改 default branch 均不可用（"Mirrored repositories"、"Events"）。
Subscribe。 只有
```
installation.*
```
events 可以在没有 subscription 的情况下到达。缺少 subscription 只会导致没有任何事件，而不是报错（"Events"）。
Verify、dedupe、acknowledge。 在解析之前，基于 raw body 验证 signature；按 delivery ID 去重；返回
```
2xx
```
，然后再处理（"Signature verification"、"Retries"、"Automatic disable"）。Origin 会对 digest 进行签名，而 Standard Webhooks 不会，因此通用 verifier 会失败。
Scopes from the spec。 请求 App 所调用 operations 的
```
x-origin-scopes.scopes
```
并集（"Scopes"）。
Opaque tokens and IDs。 不要构造或解析 page tokens 或 IDs（"Pagination"、"IDs"）。

有一个 section 名称仅看 index 很难发现：乱序到达的 check-run post 应在 "Ordering writes" 下查找。

将现有 GitHub App 迁移到 Origin 时，使用此 plugin 中的

port-github-app-to-origin

。