API Origin

Origin é a plataforma de desenvolvimento de código do Cherri Code. Sua API REST pública permite que apps e ferramentas trabalhem com repositórios, commits, verificações, pull requests e instalações de apps do Origin.

• Os Apps Origin são autenticados com JWTs de app e tokens de acesso da instalação. Consulte Autenticação.
• Consulte a especificação OpenAPI completa para ver schemas e exemplos detalhados.
• Agentes podem carregar o índice llms.txt ou a referência completa em Markdown em llms-full.txt.

Visão geral

Os apps do Origin usam um modelo de consentimento de instalação semelhante ao OAuth e de autenticação semelhante ao de um app do GitHub:

1. O app assina um JWT EdDSA de curta duração com sua chave privada Ed25519.
2. O app troca esse JWT e um ID de instalação por um token de acesso da instalação de curta duração (oit_…).
3. O token de instalação chama APIs de repositório e autentica o Git via HTTPS dentro dos repositórios e escopos aprovados para a instalação.
4. O Origin envia entregas de webhook assinadas para o URL de webhook registrado do app.

URL base

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

Os caminhos dos endpoints na referência incluem o prefixo completo /v1/origin.

Convenções de protocolo

Solicitações e respostas usam application/json. Os nomes dos campos JSON usam camelCase. Os registros de data e hora são strings RFC 3339. Inteiros Protobuf de 64 bits, incluindo números de pull request e de versão, são codificados como strings JSON.

As respostas incluem os campos que estão em seu valor padrão em vez de descartá-los, portanto um boolean false, um number 0, uma string vazia e uma matriz vazia aparecem todos no corpo. Leia o próprio valor em vez de tratar uma chave ausente como o padrão. Campos documentados como ausentes ou omitidos são opcionais no contrato e ficam fora do corpo quando não estão definidos.

Prévia

Parte da API é publicada em prévia. Ela aparece nesta referência e na especificação, mas sua estrutura pode mudar antes da disponibilidade geral. A especificação OpenAPI a marca com x-cursor-visibility: PREVIEW. O marcador pode estar em uma operação, um parâmetro, um schema ou um único campo, então uma operação estável pode, mesmo assim, retornar um campo em prévia. Endpoints em prévia exibem um badge Prévia nesta referência. Trate campos em prévia como opcionais e não crie uma dependência rígida da estrutura deles.

Primeiros passos

Acesso ao Origin

• Acesse o Origin em cursor.com/codebase.
• Gerencie as configurações do app em cursor.com/codebase/settings/apps.
• Gere uma chave de assinatura do app e registre apenas a chave pública.

CLI do Origin

Instale a CLI do Origin e faça login:

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

Clone um repositório existente:

origin repo clone '{ownerSlug}/{repoName}'# ou use o git diretamentegit clone 'https://origin.cursor.com/{ownerSlug}/{repoName}.git'

Os apps clonam usando a autenticação do Git via HTTPS com um token de acesso de instalação, e não um login de usuário.

Instalação

Envie o administrador do espaço de trabalho do cliente para:

/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

O administrador do espaço de trabalho escolhe o proprietário de destino, os escopos aprovados e todos os repositórios ou apenas os selecionados. O cliente, e não o app, controla o acesso ao repositório.

Após a aprovação, o Origin redireciona para o callback registrado:

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

Verifique o recibo de instalação e armazene o ID da instalação presente na declaração sub. Você precisará dele sempre que emitir um token de acesso da instalação.

As instalações usam um de dois modos de seleção de repositórios:

• all: a instalação pode acessar todos os repositórios pertencentes ao destino selecionado.
• selected: a instalação pode acessar apenas os repositórios selecionados pelo administrador do espaço de trabalho.

Ambos os modos abrangem repositórios espelhados e repositórios Origin nativos, portanto um espelho aparece em GET /installation/repos e pode ser selecionado. Um espelho é somente leitura até se tornar um espelho de saída estável: consulte Repositórios espelhados.

Use GET /installation/repos com um token de instalação para descobrir os repositórios disponíveis para ela. Os endpoints JWT do app podem listar, inspecionar e excluir as instalações do app. Excluir uma instalação impede a emissão de novos tokens.

Recibo de instalação

installation_receipt é um JWT compacto de curta duração assinado pela Origin. Ele comprova que a aprovação da instalação veio da Origin, e não de um redirecionamento forjado, e contém tudo de que o callback precisa. O Cherri Code não redireciona sem ele; portanto, callbacks externos sempre o incluem.

Cabeçalho JOSE:

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

Declarações:

{  "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 é o ID do seu app, e sub é o ID da instalação a ser usado ao emitir tokens de acesso da instalação.
• namespace_id é o ID estável do namespace no qual o app foi instalado.
• installedBy identifica o usuário que realizou esta instalação ou novo consentimento. Ele descreve a ação atual; portanto, em um novo consentimento, pode ser diferente do installedBy durável em Get App Installation. Ele inclui displayName quando a conta tem um nome e nunca inclui handle; em vez disso, leia o handle de uma resposta REST ou de um payload de webhook.
• Os recibos expiram cinco minutos após a emissão. jti é único para cada recibo.
• state só está presente quando a URL de instalação contém um state não vazio e reproduz esse valor. Compare-o ao valor antifalsificação que você gerou antes de redirecionar.

Verifique o recibo antes de confiar no callback: obtenha a chave de assinatura no JWKS pelo cabeçalho kid, exija alg EdDSA e typ origin-installation-receipt+jwt e valide a assinatura, iss, aud e exp. Rejeite o callback se a verificação falhar.

O recibo não é um token de acesso da instalação. Nunca o envie como credencial Bearer; emita tokens de instalação por meio de Criar token de acesso da instalação.

Autenticação

Envie credenciais REST com o esquema Bearer. Os badges Auth de cada endpoint listam os tipos de credencial que ele aceita:

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

Gere uma chave de assinatura do app

Os Apps Origin se autenticam com um par de chaves Ed25519. Gere o par localmente e registre apenas a chave pública em cursor.com/codebase/settings/apps. Um app pode ter até 10 chaves de assinatura ativas.

Crie uma chave privada PKCS#8 e uma chave pública PEM SPKI com o OpenSSL:

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

O arquivo de chave pública começa com -----BEGIN PUBLIC KEY-----. Cole esse PEM ao adicionar uma chave de assinatura. Use a chave privada correspondente apenas para assinar JWTs de app.

JWT do app

Assine um JWT de curta duração usando a chave privada Ed25519 associada a uma das chaves de assinatura ativas do app. Gere esse par conforme descrito em Gerar uma chave de assinatura do app.

Cabeçalho JOSE:

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

Declarações:

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

Defina iss e kid como o ID do app. Use uma validade de aproximadamente cinco minutos.

Authorization: Bearer APP_JWT

Use um JWT de app para operações no nível do app, como ler metadados do app, gerenciar instalações, emitir tokens de instalação e recuperar entregas de webhooks.

Token de acesso da instalação

Faça uma chamada a POST /app/installations/{installationId}/access_tokens com um JWT do app. Os tokens de acesso da instalação começam com oit_.

Authorization: Bearer oit_...

A resposta inclui expiresAt. Emita tokens conforme necessário, renove-os antes da expiração, trate-os como senhas e nunca os registre em logs.

Um token expira no máximo 15 minutos após a criação, e nunca depois do JWT do app que o solicitou, então o JWT de cinco minutos recomendado acima gera um token de no máximo cinco minutos. Leia expiresAt e emita um novo token quando esse horário passar, em vez de presumir uma duração: os tokens do Origin têm vida mais curta que os tokens de acesso da instalação do GitHub App, e uma integração que reutiliza um token seguindo a periodicidade do GitHub falha assim que o token expira. Assine o JWT com um exp mais longo quando um job precisar dos 15 minutos completos, como faz a receita de CI do CloneKit.

Remover a instalação ou excluir o app invalida seus tokens de acesso da instalação antes de expiresAt. A API REST e o Git via HTTPS rejeitam o token com 401. Não tente novamente com o mesmo token; o app deve ser reinstalado antes de poder emitir um token funcional.

Um token de acesso da instalação não pode exceder os escopos aprovados nem o acesso ao repositório da instalação. Você pode restringir um token a menos scopes ou repositoryIds. Matrizes vazias ou omitidas herdam a concessão completa da instalação.

Use tokens de acesso da instalação para operações com escopo de repositório, incluindo pull requests, gravações de check runs e Git via HTTPS.

Para agir como membro do namespace da instalação em vez de como o app, emita um token de usuário da instalação. Consulte Agindo em nome de usuários.

Autenticação do Git via HTTPS

Tokens de acesso da instalação autenticam o Git via HTTPS. O endpoint do Git usa autenticação HTTP Basic: a senha é o token de instalação, e o nome de usuário é x-access-token. As credenciais Bearer devem ser usadas na API REST; o Git via HTTPS as rejeita.

Emita um token em Criar token de acesso da instalação imediatamente antes da operação do Git. Os tokens expiram em até 15 minutos.

Clone, consultar e pull exigem repository:contents:read. Push exige repository:contents:write. O token deve incluir o repositório de destino em sua concessão.

O push também exige que o proprietário do repositório tenha permissão de gravação no Origin, o mesmo requisito exigido por Criar repositório. Se o proprietário for um usuário, ele deverá estar em um plano Pro, Pro Student, Pro+, Ultra ou Start. Se o proprietário for uma equipe, ela deverá ter um plano de equipe pago ativo, não estar no Privacy Mode (Legado) e não ter o Origin desativado por um administrador da equipe. Um push para um repositório cujo proprietário não seja elegível retorna 403. Clone, consultar e pull não têm esse requisito.

Consulte cloneUrl em Obter repositório ou List App Installation Repositories. Tanto o caminho no formato do GitHub (https://origin.cursor.com/OWNER_SLUG/REPO_NAME.git) quanto o caminho legado /git/ permitem clonar.

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

Incluir o token na URL faz com que ele seja armazenado em .git/config. Após clonar o repositório com sucesso, reescreva o remoto para que comandos posteriores não reutilizem um segredo expirado:

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

Para não incluir o token na URL remota, forneça-o pelo auxiliar de credenciais do Git:

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"

O auxiliar de credenciais da CLI do Origin é destinado ao login de usuários. As integrações de apps enviam o token de instalação, como mostrado aqui. Trate o token como uma senha, nunca o registre em logs e emita um novo antes de expiresAt se um job ainda precisar de acesso ao Git.

O Git via HTTPS tem seu próprio orçamento, separado do orçamento da REST em Limites de taxa. Uma resposta do Git cobrada inclui os mesmos cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Used, com X-RateLimit-Resource definido como git em vez de core. Solicitações do Git que excedem o orçamento retornam 429 com Retry-After e X-RateLimit-Reset. Leia os cabeçalhos para controlar o ritmo de um job, em vez de presumir um número; solicitações não tarifadas não incluem cabeçalhos de limite de taxa.

Em um repositório espelhado, um token de instalação permite clonar, consultar e fazer pull, e o Origin rejeita git push com 403 até que o espelho se torne um espelho de saída estável. Consulte Repositórios espelhados.

Solicitações da CLI autenticadas pelo usuário

Use origin api para solicitações autenticadas pelo usuário. Para uma sessão interativa, faça login pelo navegador:

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

Para uma sessão não interativa, forneça uma chave de API de usuário pessoal em Cherri Code Dashboard → API Keys:

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

A CLI troca a personal API key por um user access token de curta duração e envia esse token no header Authorization. Não envie a própria API key para um endpoint do Origin. integrações de apps devem usar JWTs dos apps e tokens de acesso da instalação.

Descoberta e chaves de assinatura

O Origin disponibiliza metadados de descoberta não autenticados e suas chaves de assinatura ativas. As mesmas chaves assinam entregas de webhook e recibos de instalação.

Os metadados de descoberta identificam o emissor e o 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 retorna JWKs Ed25519 ativos:

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

Mantenha o JWKS em cache. /keys envia Cache-Control: public, max-age=600, stale-if-error=600; reutilize uma resposta em cache por 10 minutos e depois atualize-a. Se a atualização falhar, mantenha as últimas chaves válidas por no máximo mais 10 minutos antes de a verificação falhar. Atualize também quando uma assinatura não for verificada por nenhuma chave, o que remove um ID de chave desativado. As chaves são rotacionadas semanalmente.

As assinaturas de webhook não incluem um ID de chave, portanto a verificação deve tentar cada chave Ed25519 ativa. Os recibos de instalação incluem o kid da chave de assinatura no cabeçalho JOSE, portanto a verificação dos recibos pode localizar a chave diretamente.

Escopos

Solicite apenas os escopos mínimos necessários para seu app. repository:metadata:read e o acesso aos metadados do app ou da instalação são concedidos automaticamente e não devem ser adicionados separadamente às URLs de instalação.

Solicitar um escopo :write também concede o escopo :read correspondente, então repository:labels:write cobre repository:labels:read e você não precisa listar os dois. O contrário não vale: um escopo de leitura nunca concede gravação.

O token de instalação só pode restringir essas concessões. Ele não pode adicionar um escopo ou repositório que o administrador do espaço de trabalho não aprovou.

Alterações de estado do espelhamento ficam fora desta tabela. Fazer transição do espelhamento do repositório, Forçar transição do espelhamento do repositório e Desvincular espelho do repositório usam repository:mirror:write ou repository:mirror:delete, que um app não pode solicitar na instalação: eles são fornecidos por uma credencial de usuário do Cherri Code, e quem chama também deve administrar o repositório na fonte upstream do espelho.

O gerenciamento de instalações também fica fora dela. Adicionar repositórios à instalação do app usa namespace:installations:write, que um app não pode solicitar na instalação: um administrador do namespace o mantém em uma credencial de usuário do Cherri Code, e o mesmo tipo de credencial que consentiu com a instalação é o que pode estendê-la.

O gerenciamento de apps fica fora dela pelo mesmo motivo. Criar app usa namespace:apps:create, Listar apps do namespace e Obter app usam namespace:apps:read, e Atualizar app, Adicionar chave de assinatura do app e Revogar chave de assinatura do app usam app:settings:write. Um publicador mantém essas concessões em uma credencial de usuário do Cursor; um app não pode solicitá-las para si mesmo.

A tabela abrange os escopos que um app solicita na instalação. Para consultar o escopo exigido por uma única operação, leia sua extensão x-origin-scopes na especificação OpenAPI. Essa extensão abrange todas as operações, incluindo os escopos app, installation e namespace, que acompanham a própria credencial, em vez de serem concedidos por uma instalação. Uma operação cujos escopos vêm todos com a credencial marca sua extensão como ambient: true: não há nada a solicitar para ela, e basta apresentar a credencial correta.

Repositórios espelhados

Uma instalação usa todos os escopos que possui em um repositório Origin nativo e em um espelho de saída estável. Em um repositório em qualquer outro estado de espelhamento, apenas dois escopos se aplicam:

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

Todos os outros escopos retornam 403 nesse repositório, independentemente do que o administrador do espaço de trabalho tenha aprovado. Pela API REST, a leitura de repositórios e conteúdos, a comparação de commits e Sincronizar espelho continuam funcionando, e o Origin rejeita pull requests, revisões, comentários, verificações, conjuntos de regras e qualquer operação de gravação. Pelo Git via HTTPS, clone, consultar, pull e download de LFS continuam funcionando, e o Origin rejeita push e upload de LFS.

Tirar um repositório desse estado é uma operação que requer credenciais de usuário, e não algo que uma instalação possa fazer: Fazer transição do espelhamento do repositório avança a direção do espelho, Forçar transição do espelhamento do repositório faz a transição para a fonte upstream sem enviar referências divergentes de volta, e Desvincular espelho do repositório desconecta o espelho definitivamente.

O objeto mirror de um repositório não informa se operações de gravação são permitidas. Um espelho em transição pode informar mirror.status como outbound e ainda ser somente leitura; portanto, considere o 403 como definitivo, em vez de tomar decisões com base em mirror.status.

Limites de taxa

A API Origin usa um orçamento de pontos compartilhado por principal, redefinido em uma janela móvel de um minuto. Cada tipo de principal autenticado tem seu próprio orçamento:

Cada endpoint consome um custo fixo desse orçamento antes da execução do manipulador. Falhas de autenticação e autorização não consomem pontos.

O Cherri Code pode aumentar os orçamentos por minuto de cada app para parceiros de design. Entre em contato com o Cherri Code se sua integração precisar de um limite maior.

Cabeçalhos de resposta

As respostas cobradas e Consultar limite de taxa incluem:

X-RateLimit-Reset informa uma janela completa de 60 segundos a partir do momento da resposta. A janela do contador começa com a primeira solicitação cobrada em uma sequência, e não no início de um minuto do calendário.

Limite excedido

Quando uma solicitação exceder o orçamento, a API retornará HTTP 429 com:

• Retry-After: número de segundos a aguardar antes de tentar novamente (60)
• Os mesmos cabeçalhos X-RateLimit-*, com X-RateLimit-Remaining definido como 0

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

Aguarde Retry-After ou até X-RateLimit-Reset antes de tentar novamente. Use backoff com jitter quando chamadores simultâneos compartilham o mesmo token de instalação.

Verificar a cota restante

Chame Consultar limite de taxa para consultar o orçamento atual sem consumir pontos. O corpo da resposta reflete os cabeçalhos X-RateLimit-* do recurso compartilhado core.

Convenções gerais

Paginação

Endpoints paginados aceitam:

• pageSize: o valor padrão é 30, com limite máximo de 100.
• pageToken: token opaco retornado pela página anterior. Não o inspecione nem o construa.

As respostas usam um campo de coleção específico do resource e nextPageToken. Ele fica vazio quando não existe uma próxima página. As respostas públicas de lista não incluem contagens totais. Os tokens de página são vinculados ao resource de origem e aos filtros. Reinicie a paginação quando os filtros forem alterados. Tokens não vazios inválidos ou incompatíveis retornam 400.

Envie o mesmo pageSize em todas as solicitações de uma sequência, incluindo as continuações. Na maioria dos endpoints de listagem, um pageSize enviado com um token de página se aplica a essa página, e o tamanho de página anterior é mantido quando ele é omitido; as entradas de pageToken desses endpoints indicam isso. Nos demais, o que um token de página guarda varia, portanto um pageSize constante garante o mesmo tamanho de página em todos os endpoints.

Erros

Os erros usam um corpo no estilo RPC do Google:

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

Os status HTTP mais comuns são 400, 401, 403, 404, 429, 500 e 503. Algumas operações do banco de dados do Git também retornam 409 em caso de conflitos no estado do repositório. Consulte Limites de taxa para ver os cabeçalhos e o comportamento de nova tentativa de 429.

Use o status HTTP e o code para diferenciar os erros. Trate message como texto voltado para desenvolvedores.

Um 404 nunca diferencia um recurso que não existe de um ao qual seu app não consegue acessar. Interprete-o como "não disponível para esta instalação", em vez de considerá-lo uma prova de que o recurso está ausente.

details contém entradas tipadas: violações de campo google.rpc.BadRequest em caso de argumento inválido e uma entrada google.rpc.RequestInfo em todos os erros. Origin pode adicionar tipos de detalhe a qualquer momento; portanto, ignore entradas que sua integração não reconhece.

Cada resposta de erro inclui o ID da solicitação duas vezes: em um cabeçalho de resposta X-Request-ID e como uma entrada google.rpc.RequestInfo em details. Origin repete o x-request-id que você enviou ou gera um quando você não envia nenhum. A entrada RequestInfo está presente mesmo quando message é um erro interno opaco; portanto, informe o ID da solicitação ao entrar em contato com o Cherri Code sobre uma chamada com falha.

Caminhos sem correspondência em /v1/origin e solicitações que usam o método incorreto em um caminho conhecido retornam esse mesmo corpo em vez de um erro genérico do roteador. A mensagem informa o método e o caminho e nunca repete a string de consulta.

IDs

Os IDs de resource são strings opacas com um prefixo de tipo, como app_… para um app e i_… para uma instalação. Armazene e compare esses IDs como strings completas. Não faça parsing deles, não tente extrair significado dos seus caracteres nem dependa da ordem de classificação deles.

Um ID permanece o mesmo durante toda a vida útil do seu resource, enquanto nomes e slugs podem mudar. Um repositório mantém o mesmo ID mesmo quando é renomeado. Por isso, use o ID como chave dos dados em cache, em vez de {ownerSlug}/{repoName}, e referencie o repositório pelo ID, conforme descrito em Caminhos de repositório.

Caminhos de repositório

Caminhos no escopo do repositório usam o slug do proprietário e o nome do repositório no formato {ownerSlug}/{repoName}. Ambos os segmentos são resolvidos sem distinção entre maiúsculas e minúsculas, portanto qualquer combinação de maiúsculas e minúsculas acessa o repositório. As respostas retornam o nome e o slug armazenados, em vez da capitalização enviada, e as URLs Git HTTPS são resolvidas da mesma forma. Compare nomes de repositórios sem distinguir maiúsculas de minúsculas e consulte a capitalização canônica em Obter repositório.

Todo caminho no escopo do repositório também aceita o ID estável do repositório no lugar do par: envie _ como o slug do proprietário e o ID como o nome do repositório, como em GET /v1/origin/repos/_/REPO_ID. Consulte o ID no campo id em Obter repositório. O marcador _ não pode ser usado como slug de proprietário, portanto as duas formas nunca entram em conflito. Em uma solicitação Connect ou JSON, defina ownerSlug como _ e name como o ID.

A forma com ID permanece válida após uma renomeação, o que a torna uma forma estável de identificar um repositório. Ela não concede nada por si só: depois que o Origin resolve o ID para um repositório, seu app ainda precisa ter o mesmo escopo nesse repositório. Um ID ao qual seu app não consegue acessar retorna o mesmo corpo 404 de um ID inexistente, portanto uma resposta nunca confirma a existência de um repositório. Um ID malformado retorna 400. Create Repo aceita apenas um slug de proprietário e rejeita _.

Referências de recursos

Os snapshots de recursos contêm os campos atuais do recurso. O contexto do contêiner usa referências compactas em vez de duplicar recursos completos:

• RepositoryReference identifica um repositório.
• PullRequestReference identifica uma pull request e inclui a referência ao repositório.
• ThreadReference identifica a thread que contém um comentário de pull request.
• OriginActor identifica um ator público como user, app ou serviceAccount. Exatamente uma variante está presente; leia a identidade dessa variante.

Execuções de verificação

Os Apps relatam resultados de CI como suítes de verificações e execuções de verificação associadas a um commit por meio de Post Check Run e Batch Upsert Check Runs, e os consultam de volta pelos endpoints de Checks. Esta seção define os termos comuns a esses endpoints: qual tentativa é a atual, como o Origin ordena e relata gravações e como se comportam timestamps e prazos.

Tentativas e a tentativa atual

Cada (actor, key, externalId) relatado em um commit é uma tentativa de suíte, e cada (suite, key, externalId) dentro dela é uma tentativa de execução. Reutilizar um externalId atualiza essa tentativa no próprio lugar; um novo externalId inicia uma nova tentativa e mantém a anterior como histórico. Tentativas substituídas continuam acessíveis para leitura por id em Obter suíte de verificações e Obter execução de verificação.

Onde a API mostra as verificações atuais de um commit — em Listar suítes de verificações de um commit, Listar execuções de verificação de um commit e no estado de CI e nas verificações obrigatórias do pull request —, o Origin consolida as tentativas em duas etapas:

1. A tentativa de suíte atual por (actor, key) é aquela cujas execuções atuais, conforme selecionadas pela segunda etapa, têm o externalUpdatedAt mais recente; uma suíte sem execuções é classificada por seu createdAt. Empates são resolvidos pelo createdAt da suíte e depois por seu id, do mais recente para o mais antigo.
2. Dentro dessa tentativa de suíte, a execução atual de uma key é a que tem o externalUpdatedAt mais recente. Empates são resolvidos por createdAt e depois por id, do mais recente para o mais antigo.

Listar execuções de verificação de uma suíte aplica a segunda etapa à suíte que você indicar. Uma execução só é a atual do commit quando sua suíte é a tentativa de suíte atual desse commit. Como a primeira etapa classifica tentativas de suíte inteiras, uma execução publicada sob uma tentativa de suíte substituída fica fora das verificações do commit enquanto outra tentativa mantiver um externalUpdatedAt mais recente; assim que seu timestamp passar a ser o mais recente, sua tentativa de suíte se torna a atual e passam a ficar ocultas as execuções da outra tentativa.

Uma tentativa cancelada não substitui uma que passou. Em qualquer uma das etapas, uma tentativa cancelada fica abaixo das outras tentativas de sua key quando a tentativa mais recente dessa key que não foi cancelada passou. Uma execução passou quando está completed com a conclusão success, neutral ou skipped. Uma tentativa de suíte passou quando todas as suas execuções atuais passaram e é considerada cancelada quando todas as suas execuções atuais estão completed, pelo menos uma com a conclusão cancelled e as demais tendo passado. Quando a reexecução da tentativa que passou é solicitada, as tentativas canceladas cujo externalUpdatedAt é igual ou posterior à solicitação voltam a ser classificadas por seus timestamps. Uma tentativa de suíte cancelada mais recente ainda substitui uma mais antiga que não passou por completo.

Uma execução cuja reexecução foi solicitada mantém seu lugar como a tentativa atual de sua key e aparece como pendente até que o app responsável responda: veja Solicitar novamente a execução de verificação.

Ordenação de gravações

O Origin ordena os posts destinados a uma mesma execução — ou seja, o mesmo externalId e key dentro da suíte — por checkRun.externalUpdatedAt, com precisão de milissegundos. Um post só é aplicado quando seu valor é igual ou posterior ao externalUpdatedAt armazenado da execução, elevado a rerequestedAt enquanto houver uma nova solicitação pendente. Valores iguais são aplicados, então o post mais recente prevalece, com duas exceções que também são tratadas como obsoletas: um post queued ou in_progress não pode reabrir uma execução completed no mesmo timestamp, e um post exatamente no timestamp armazenado é ignorado enquanto rerequestedAt estiver definido. Um valor mais recente é aplicado, inclusive para reabrir uma execução completed, com uma exceção tratada como obsoleta independentemente do timestamp: um post completed com conclusão cancelled não pode substituir uma execução completed cuja conclusão seja success, neutral ou skipped.

Um post obsoleto ainda assim é bem-sucedido. A resposta é HTTP 200 com a suíte e a execução armazenadas, e não com os valores enviados, e o updatedAt da execução não avança. Cada execução enviada retorna como um par: checkRun, a execução armazenada após a chamada, e outcome, o que a gravação fez com ela. Post execução de verificação retorna o par no nível superior da resposta, ao lado de checkSuite. Batch Upsert execuções de verificação retorna um par por execução enviada em results[], na ordem da solicitação, de modo que um elemento do batch carrega o mesmo resultado por execução que a chamada única traz inline. Leia outcome, ou cada results[].outcome, para saber o que a gravação fez:

O updatedAt não avança em um post unchanged nem em um ignored_stale, portanto não serve para distinguir um do outro; somente outcome serve. Trate um valor não reconhecido como "a execução armazenada está na resposta; não se sabe se houve gravação". Em um batch, o Origin aplica a regra a cada execução separadamente: uma execução obsoleta não faz o batch falhar, e results[] traz a execução armazenada na posição correspondente, com outcome ignored_stale.

Em Batch Upsert execuções de verificação, o checkRuns[] de nível superior está descontinuado em favor de results[]. Ele continua sendo preenchido com as mesmas execuções armazenadas, na mesma ordem, mas não carrega outcomes; leia results[] em vez dele. Isso se aplica apenas ao batch: em Post execução de verificação, checkRun e outcome são os campos de nível superior a serem lidos.

Timestamps e prazos

Um post cujo externalUpdatedAt, startedAt ou completedAt esteja mais de 60 segundos no futuro retorna InvalidArgument (HTTP 400). completedAt não pode ser anterior a startedAt quando ambos estão no mesmo post. deadlineAt não pode estar mais de 24 horas no futuro.

Somente um run in_progress expira. Depois que seu deadlineAt passa, uma varredura periódica o conclui com a conclusão timed_out, define completedAt caso o run ainda não tenha um, limpa deadlineAt e entrega repository.check_run.completed. A expiração ocorre alguns minutos depois do prazo, e não exatamente nele: por padrão, a varredura roda mais ou menos a cada 30 minutos, uma configuração operacional que pode mudar, portanto não dependa desse intervalo. Um run queued nunca expira, assim como um run sem deadlineAt. Um post completed limpa o prazo. O Origin não altera externalUpdatedAt ao expirar um run, de modo que um post posterior com um externalUpdatedAt mais recente ainda se aplica a um run expirado.

Limitações atuais

• A listagem de repositórios em todo o namespace e a criação de repositórios não fazem parte da API de parceiros. Descubra os repositórios pela instalação.
• A comparação de commits retorna dados de resumo, e não uma lista de commits incorporada. Os arquivos alterados têm seu próprio endpoint paginado, Listar arquivos de comparação.
• As threads podem ser acessadas apenas para resolução. Não há um endpoint que liste threads diretamente; leia-as nos comentários que contêm.
• Webhooks de push não incluem uma lista completa de commits.
• O merge de pull request oferece suporte a repositórios Origin nativos. Repositórios espelhados são rejeitados.
• Um repositório espelhado é somente leitura para uma instalação até se tornar um espelho de saída estável. Consulte Repositórios espelhados.

Checklist de implementação

• Armazene a chave privada Ed25519 em um gerenciador de segredos e rotacione as chaves de forma planejada. Veja Gerar uma chave de assinatura do app.
• Verifique o recibo de instalação em callbacks de instalação e leia o ID de instalação e state nas claims dele.
• Use JWTs de curta duração do app e emita tokens de instalação no momento necessário.
• Use tokens de instalação, não JWTs do app, para APIs com escopo de repositório, gravações de execuções de verificação e Git HTTPS.
• Solicite os escopos mínimos e o acesso mínimo ao repositório.
• Trate os tokens de página como opacos e reinicie a paginação quando os filtros mudarem.
• Mantenha os valores de key de verificações estáveis e legíveis. Use um novo externalId imutável para cada tentativa e valores crescentes de externalUpdatedAt para atualizações.
• Leia outcome em cada resposta de Post Check Run e cada results[].outcome em cada resposta de Batch Upsert Check Runs; um post obsoleto retorna 200 com a execução armazenada. Veja Execuções de verificação.
• Verifique as assinaturas de webhook em relação ao corpo bruto da solicitação antes de analisá-lo.
• Elimine entregas duplicadas usando webhook-id e processe-as de forma assíncrona após retornar 2xx.
• Ignore campos JSON desconhecidos para manter a compatibilidade futura.
• Respeite os cabeçalhos Retry-After e X-RateLimit-*. Use Consultar limite de taxa para monitorar os pontos restantes sem consumi-los.

Referência de endpoints

Baixe a especificação OpenAPI para consultar os schemas completos dos componentes. O documento declara https://api.cursor.com como seu servidor e um esquema de segurança HTTP bearer bearerAuth, e cada operação lista os códigos de resposta que ela pode retornar, além de um exemplo de solicitação e de resposta. Cada operação também traz uma extensão x-origin-scopes: scopes contém o escopo exigido pela operação e tokenTypes contém os tipos de credencial que ela aceita. Cada schema de payload de webhook traz uma extensão x-origin-webhook-events que lista os eventos que o entregam, e as superfícies em prévia trazem x-cursor-visibility: PREVIEW. Os parâmetros de caminho têm os mesmos nomes usados pelas URLs: ownerSlug e repoName. Cada operação traz um operationId único; quando uma mesma operação atende a dois formatos de URL, o id do segundo formato recebe o sufixo _2, como em OriginService_GetRepoTarball_2.

Os snippets JSON mostram valores de placeholder compatíveis com o schema. As descrições dos campos de resposta refletem o schema OpenAPI e o contrato atual da plataforma.

Apps e instalações

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

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

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

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

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

204 No Content

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

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

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

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

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

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}

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

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

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

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

204 No Content

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

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

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

Repositórios

cloneUrl é uma URL HTTPS de clonagem disponível apenas na saída. Obter repositório inclui cloneUrl.

Os parceiros encontram seus repositórios por meio de Listar repositórios da instalação do app. A listagem e a criação de repositórios em todo o namespace não fazem parte da API de parceiros.

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

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

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

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}

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

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

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

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}

Os endpoints de transição de espelhamento estão documentados na Origin Migration API. Sincronizar espelhamento permanece nesta página.

Desvincular espelho do repositório

Consulte Desvincular espelho do repositório.

Obter job de transição de espelhamento

Consulte Obter job de transição de espelhamento.

Obter job de transição de espelhamento ativo

Veja Obter job de transição de espelhamento ativo.

Forçar transição do espelhamento do repositório

Consulte Forçar transição do espelhamento do repositório.

Fazer transição do espelhamento do repositório

Consulte Fazer transição do espelhamento do repositório.

Verificações

• O primeiro upsert de execução cria automaticamente a suíte correspondente.
• As verificações obrigatórias são associadas ao app instalador, à key da suíte e, opcionalmente, à key de uma execução. name serve apenas para exibição e não é usado na associação.
• Mantenha os valores de key estáveis entre as tentativas e legíveis para os usuários, pois a configuração de verificações obrigatórias é baseada neles.
• Reutilize externalId para atualizar uma tentativa, o que descarta o resultado anterior dessa tentativa; use um novo externalId ao tentar novamente, para que a tentativa anterior permaneça no histórico.
• Use checkRun.output para resultados legíveis por humanos:
  • title: título curto do resultado, com até 255 caracteres.
  • summary: resumo principal em Markdown, com até 65.535 bytes UTF-8.
  • text: detalhes estendidos em Markdown, com até 65.535 bytes UTF-8.
• Use detailsUrl para criar um link para a página de resultados externos do provedor.

Execuções de verificação define qual tentativa é a atual, como externalUpdatedAt ordena as gravações e o que outcome relata, além das regras de timestamp e prazo compartilhadas por esses endpoints.

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

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