API de Origin

Origin es la plataforma de forja de código de Cherri Code. Su API REST pública permite que las aplicaciones y herramientas interactúen con los repositorios, commits, comprobaciones, pull requests e instalaciones de aplicaciones de Origin.

• Las aplicaciones de Origin se autentican con JWT de aplicación y tokens de acceso de instalación. Consulte Autenticación.
• Consulte la especificación de OpenAPI completa para ver esquemas y ejemplos detallados.

• Los agentes de programación pueden cargar el índice llms.txt o la referencia completa en Markdown en llms-full.txt.

Descripción general

Las aplicaciones de Origin implementan un consentimiento de instalación al estilo de OAuth y un modelo de autenticación al estilo de las aplicaciones de GitHub:

1. La aplicación firma un JWT de EdDSA de corta duración con su clave privada Ed25519.
2. La aplicación intercambia ese JWT y un ID de instalación por un token de acceso de instalación de corta duración (oit_…).
3. El token de instalación llama a las API de repositorios y autentica Git a través de HTTPS dentro de los repositorios y ámbitos aprobados de la instalación.
4. Origin envía entregas de webhooks firmadas a la URL de webhook registrada de la aplicación.

URL base

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

Las rutas de los endpoints de la referencia incluyen el prefijo /v1/origin completo.

Convenciones del protocolo

Las solicitudes y las respuestas usan application/json. Los nombres de los campos JSON usan camelCase. Las marcas de tiempo son cadenas con formato RFC 3339. Los enteros Protobuf de 64 bits, incluidos los números de pull request y de versión, se codifican como cadenas JSON.

Las respuestas incluyen los campos que tienen su valor predeterminado en lugar de descartarlos, por lo que un booleano false, un número 0, una cadena vacía y un array vacío aparecen todos en el cuerpo. Lee el valor en sí en lugar de interpretar una clave ausente como el valor predeterminado. Los campos documentados como ausentes u omitidos son opcionales en el contrato y quedan fuera del cuerpo cuando no se establecen.

Vista previa

Parte de la superficie de la API se publica en vista previa. Aparece en esta referencia y en la especificación, pero su estructura puede cambiar antes de su disponibilidad general. La especificación de OpenAPI la marca con x-cursor-visibility: PREVIEW. El marcador puede aplicarse a una operación, un parámetro, un esquema o un solo campo, por lo que una operación estable puede devolver igualmente un campo en vista previa. Los endpoints en vista previa muestran la insignia Preview en esta referencia. Trata los campos en vista previa como opcionales y no crees una dependencia estricta de su estructura.

Primeros pasos

Acceso a Origin

• Explora Origin en cursor.com/codebase.
• Gestiona los ajustes de la aplicación en cursor.com/codebase/settings/apps.
• Genera una clave de firma para la aplicación y registra solo la clave pública.

CLI de Origin

Instala la CLI de Origin e inicia sesión:

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

Clona un repositorio existente:

origin repo clone '{ownerSlug}/{repoName}'# o usa git directamentegit clone 'https://origin.cursor.com/{ownerSlug}/{repoName}.git'

Las aplicaciones clonan mediante la autenticación de Git por HTTPS con un token de acceso de instalación, no con el inicio de sesión de un usuario.

Instalación

Indica al administrador del espacio de trabajo del cliente que vaya a:

/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

El administrador del espacio de trabajo elige el propietario de destino, los ámbitos aprobados y todos los repositorios o solo los repositorios seleccionados. El cliente, no la aplicación, controla el acceso al repositorio.

Tras la aprobación, Origin redirige al callback registrado:

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

Verifica el recibo de instalación y luego guarda el ID de instalación de la afirmación sub del recibo. Lo necesitarás siempre que emitas un token de acceso de instalación.

Las instalaciones usan uno de estos dos modos de selección de repositorios:

• all: la instalación puede acceder a todos los repositorios propiedad del destino seleccionado.
• selected: la instalación solo puede acceder a los repositorios seleccionados por el administrador del espacio de trabajo.

Ambos modos incluyen repositorios replicados y repositorios nativos de Origin, por lo que una réplica aparece en GET /installation/repos y puede seleccionarse. Una réplica es de solo lectura hasta que se convierte en una réplica saliente estable: consulta Repositorios replicados.

Usa GET /installation/repos con un token de instalación para consultar los repositorios disponibles para esa instalación. Los endpoints JWT de aplicación permiten listar, inspeccionar y eliminar las instalaciones de la app. Eliminar una instalación impide emitir nuevos tokens.

Recibo de instalación

installation_receipt es un JWT compacto de corta duración firmado por Origin. Demuestra que la aprobación de la instalación provino de Origin y no de una redirección falsificada, e incluye todo lo que necesita el callback. Cherri Code no redirige sin él, por lo que los callbacks externos siempre lo incluyen.

Encabezado JOSE:

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

Afirmaciones:

{  "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 es el ID de tu app y sub es el ID de la instalación que debes usar al emitir tokens de acceso de instalación.
• namespace_id es el ID estable del espacio de nombres en el que se instaló la app.
• installedBy identifica al usuario que realizó esta instalación o volvió a dar su consentimiento. Describe la acción actual, por lo que, al volver a dar su consentimiento, puede diferir del installedBy duradero de Obtener instalación de app. Incluye displayName cuando la cuenta tiene un nombre y nunca incluye handle; lee el handle de una respuesta REST o de un payload de webhook.
• Los recibos caducan cinco minutos después de su emisión. jti es único para cada recibo.
• state solo está presente cuando la URL de instalación incluía un state no vacío y reproduce ese valor. Compáralo con el valor antifalsificación que generaste antes de redirigir.

Verifica el recibo antes de confiar en el callback: obtén la clave de firma del JWKS mediante el encabezado kid, exige alg EdDSA y typ origin-installation-receipt+jwt, y valida la firma, iss, aud y exp. Rechaza el callback si falla la verificación.

El recibo no es un token de acceso de instalación. No lo envíes nunca como credencial Bearer; en su lugar, emite tokens de instalación mediante Crear token de acceso de instalación.

Autenticación

Envía las credenciales REST con el esquema Bearer. Los badges de Auth de cada endpoint indican los tipos de credenciales que acepta:

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

Generar una clave de firma para una aplicación

Las aplicaciones de Origin se autentican con un par de claves Ed25519. Genere el par localmente y registre solo la clave pública en cursor.com/codebase/settings/apps. Una aplicación puede tener hasta 10 claves de firma activas.

Cree una clave privada PKCS#8 y una clave pública PEM SPKI con OpenSSL:

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

El archivo de clave pública comienza con -----BEGIN PUBLIC KEY-----. Pegue ese PEM al añadir una clave de firma. Use la clave privada correspondiente únicamente para firmar JWT de aplicación.

JWT de aplicación

Firma un JWT de corta duración con la clave privada Ed25519 asociada a una de las claves de firma activas de la aplicación. Genera ese par como se describe en Generar una clave de firma de aplicación.

Encabezado JOSE:

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

Afirmaciones:

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

Establece iss y kid con el ID de la aplicación. Usa una validez de aproximadamente cinco minutos.

Authorization: Bearer APP_JWT

Usa un JWT de aplicación para realizar operaciones a nivel de aplicación, como leer los metadatos de la aplicación, gestionar instalaciones, emitir tokens de instalación y recuperar entregas de webhooks.

Token de acceso de instalación

Realiza una solicitud a POST /app/installations/{installationId}/access_tokens con un JWT de aplicación. Los tokens de acceso de instalación comienzan con oit_.

Authorization: Bearer oit_...

La respuesta incluye expiresAt. Emite tokens justo a tiempo, renuévalos antes de que caduquen, trátalos como contraseñas y nunca los registres.

Un token caduca como máximo 15 minutos después de su creación, y nunca más tarde que el JWT de aplicación que lo solicitó, por lo que el JWT de cinco minutos recomendado arriba produce un token de cinco minutos como máximo. Lee expiresAt y emite un nuevo token cuando se supere, en lugar de dar por supuesta una duración: los tokens de Origin tienen una vida más corta que los tokens de acceso de instalación de las GitHub Apps, y una integración que reutilice un token siguiendo la planificación de GitHub fallará en cuanto el token caduque. Firma el JWT con un exp posterior cuando un job necesite los 15 minutos completos, tal como hace la receta de CI de CloneKit.

Eliminar la instalación o eliminar la aplicación invalida sus tokens de acceso de instalación antes de expiresAt. La API REST y Git por HTTPS rechazan entonces el token con 401. No lo reintentes con el mismo token; la aplicación debe reinstalarse antes de poder emitir uno funcional.

Un token de acceso de instalación no puede exceder los ámbitos aprobados ni el acceso a repositorios de la instalación. Puedes restringir un token a menos scopes o repositoryIds. Los arrays vacíos u omitidos heredan el grant completo de la instalación.

Usa tokens de acceso de instalación para operaciones con ámbito de repositorio, incluidos los pull requests, las escrituras de comprobaciones de ejecución y Git por HTTPS.

Para actuar como miembro del espacio de nombres de la instalación en lugar de hacerlo como la aplicación, emite un token de usuario de instalación. Consulta Actuar en nombre de usuarios.

Autenticación de Git por HTTPS

Los tokens de acceso de instalación autentican Git por HTTPS. El endpoint de Git usa autenticación HTTP Basic: la contraseña es el token de instalación y el nombre de usuario es x-access-token. Las credenciales Bearer se usan con la API REST; Git por HTTPS las rechaza.

Emita un token desde Crear token de acceso de instalación inmediatamente antes de la operación de Git. Los tokens caducan en un máximo de 15 minutos.

Clone, fetch y pull requieren repository:contents:read. Hacer push requiere repository:contents:write. El token debe incluir el repositorio de destino en su concesión.

Hacer push también requiere que el propietario del repositorio pueda escribir en Origin, el mismo requisito que exige Crear repositorio. Si el propietario es un usuario, debe tener un plan Pro, Pro Student, Pro+, Ultra o Start. Si el propietario es un equipo, debe tener un plan de equipo de pago activo, no debe estar en modo de privacidad (heredado) y Origin no debe estar desactivado por un administrador de equipo. Hacer push a un repositorio cuyo propietario no cumple los requisitos devuelve 403. Clone, fetch y pull no tienen este requisito.

Obtenga cloneUrl desde Get Repo o Listar repositorios de la instalación de la aplicación. Tanto la ruta con formato de GitHub (https://origin.cursor.com/OWNER_SLUG/REPO_NAME.git) como la ruta heredada /git/ permiten clonar.

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

Incluir el token en la URL lo guarda en .git/config. Después de clonar correctamente, actualiza el remoto para que los comandos posteriores no reutilicen un secreto vencido:

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

Para evitar incluir el token en la URL remota, proporciónalo mediante el asistente de credenciales de 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"

El asistente de credenciales de CLI de Origin es para el inicio de sesión de usuarios. Las integraciones de aplicaciones envían el token de instalación, como se muestra aquí. Trata el token como una contraseña: nunca lo registres y emite uno nuevo antes de expiresAt si un trabajo aún necesita acceso a Git.

Git por HTTPS mide su propio presupuesto, separado del presupuesto de REST en Límites de uso. Una respuesta de Git con cargo incluye los mismos encabezados X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Used, con X-RateLimit-Resource establecido en git en lugar de core. Las solicitudes de Git que exceden el presupuesto devuelven 429 con Retry-After y X-RateLimit-Reset. Consulta los encabezados para ajustar el ritmo de un trabajo en lugar de suponer un número; las solicitudes sin medición no incluyen encabezados de límite de uso.

En un repositorio replicado, un token de instalación permite clonar, hacer fetch y pull, y Origin rechaza git push con 403 hasta que la réplica se convierta en una réplica saliente estable. Consulta Repositorios replicados.

Solicitudes de CLI autenticadas por usuario

Usa origin api para las solicitudes autenticadas por usuario. Para una sesión interactiva, inicia sesión desde tu navegador:

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

Para una sesión no interactiva, proporciona una clave de API de usuario personal desde Cherri Code Dashboard → API Keys:

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

La CLI intercambia la clave de API personal por un token de acceso de usuario de corta duración y luego envía ese token en el header Authorization. No envíes la clave de API directamente a un endpoint de Origin. Las integraciones de aplicación deben usar JWT de aplicación y tokens de acceso de instalación.

Descubrimiento y claves de firma

Origin publica metadatos de descubrimiento sin autenticación y sus claves de firma activas. Las mismas claves firman las entregas de webhooks y los recibos de instalación.

Los metadatos de descubrimiento identifican al emisor y 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 devuelve JWK de Ed25519 activos:

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

Guarda el JWKS en caché. /keys envía Cache-Control: public, max-age=600, stale-if-error=600, así que reutiliza una respuesta en caché durante 10 minutos y luego actualízala; si la actualización falla, conserva las últimas claves válidas durante un máximo de otros 10 minutos antes de que falle la verificación. Actualiza también si una firma no se puede verificar con ninguna clave, lo que elimina un ID de clave retirado. Las claves se rotan semanalmente.

Las firmas de webhook no incluyen un ID de clave, por lo que la verificación debe probar cada clave Ed25519 activa. Los recibos de instalación incluyen el kid de la clave de firma en su cabecera JOSE, por lo que la verificación de recibos puede resolver la clave directamente.

Ámbitos

Solicita únicamente los ámbitos mínimos que necesite tu aplicación. repository:metadata:read y el acceso a los metadatos de la aplicación o de la instalación se conceden automáticamente y no deben añadirse por separado a las URL de instalación.

Solicitar un ámbito :write también concede el ámbito :read correspondiente, por lo que repository:labels:write abarca repository:labels:read y no es necesario enumerar ambos. Lo contrario no se cumple: un ámbito de lectura nunca concede permisos de escritura.

El token de instalación solo puede restringir estos grants. No puede añadir un ámbito ni un repositorio que el administrador del espacio de trabajo no haya aprobado.

Los cambios de estado de la replicación quedan fuera de esta tabla. Transition Repo Mirror, Force Repo Mirror Cutover y Desvincular réplica de repositorio requieren repository:mirror:write o repository:mirror:delete, que una aplicación no puede solicitar durante la instalación: los proporciona una credencial de usuario de Cherri Code, y quien realiza la llamada también debe administrar el repositorio en la fuente ascendente de la replicación.

La gestión de instalaciones también queda fuera. Add App Installation Repositories requiere namespace:installations:write, que una aplicación no puede solicitar durante la instalación: lo mantiene un administrador del espacio de nombres en una credencial de usuario de Cherri Code, y el mismo tipo de credencial que consintió la instalación es el que puede ampliarla.

La gestión de aplicaciones queda fuera por la misma razón. Crear aplicación requiere namespace:apps:create, List Namespace Apps y Get App requieren namespace:apps:read, y Update App, Add App Signing Key y Revoke App Signing Key requieren app:settings:write. Un publicador mantiene estos ámbitos en una credencial de usuario de Cursor; una aplicación no puede solicitarlos para sí misma.

La tabla abarca los ámbitos que solicita una aplicación durante la instalación. Para consultar el ámbito que requiere una operación concreta, lee su extensión x-origin-scopes en la especificación de OpenAPI. Esa extensión abarca todas las operaciones, incluidos los ámbitos app, installation y namespace que vienen con la propia credencial en lugar de con un grant de instalación. Una operación cuyos ámbitos vienen todos con la credencial marca su extensión como ambient: true: no hay nada que solicitar para ella y basta con presentar la credencial correcta.

Repositorios replicados

Una instalación usa todos los ámbitos que tiene en un repositorio nativo de Origin y en una réplica saliente estable. En un repositorio con cualquier otro estado de réplica, solo se aplican dos ámbitos:

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

Todos los demás ámbitos devuelven 403 en ese repositorio, independientemente de lo que haya aprobado el administrador del espacio de trabajo. A través de la API REST, siguen funcionando las lecturas del repositorio y del contenido, la comparación de commits y Sync Mirror; Origin rechaza los pull requests, las revisiones, los comentarios, las comprobaciones, los conjuntos de reglas y cualquier operación de escritura. A través de Git por HTTPS, siguen funcionando clone, fetch, pull y la descarga de LFS; Origin rechaza push y la carga de LFS.

Sacar un repositorio de ese estado es una operación que requiere credenciales de usuario, no algo que pueda hacer una instalación: Transition Repo Mirror hace avanzar la dirección de la réplica, Force Repo Mirror Cutover cambia a la fuente ascendente sin enviar de vuelta las refs divergentes y Detach Repo Mirror desconecta definitivamente la réplica.

El objeto mirror de un repositorio no indica si se permiten operaciones de escritura. Una réplica en plena transición puede informar de que mirror.status es outbound y seguir siendo de solo lectura, así que considera el 403 como la fuente de autoridad en lugar de basarte en mirror.status.

Límites de uso

La API de Origin utiliza un presupuesto compartido de puntos por entidad principal que se restablece en una ventana móvil de un minuto. Cada tipo de entidad principal autenticada tiene su propio presupuesto:

Cada endpoint aplica un coste fijo a ese presupuesto antes de ejecutar el controlador. Los errores de autenticación y autorización no consumen puntos.

Cherri Code puede aumentar los presupuestos por minuto de cada aplicación para los partners de diseño. Contacta con Cherri Code si tu integración necesita un límite mayor.

Encabezados de respuesta

Las respuestas facturadas y Obtener límite de uso incluyen:

X-RateLimit-Reset indica una ventana completa de 60 segundos desde el momento de la respuesta. La ventana del contador comienza con la primera solicitud facturada de una ráfaga, no en el límite de un minuto natural.

Superar el límite

Cuando una solicitud supera el presupuesto, la API devuelve HTTP 429 con:

• Retry-After: segundos de espera antes de reintentar (60)
• Los mismos encabezados X-RateLimit-*, con X-RateLimit-Remaining establecido en 0

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

Espera Retry-After o hasta X-RateLimit-Reset antes de reintentar. Usa una espera progresiva con fluctuación cuando varios clientes simultáneos compartan un mismo token de instalación.

Consultar la cuota restante

Llame a Obtener límite de uso para consultar el presupuesto actual sin consumir puntos. El cuerpo de la respuesta refleja los encabezados X-RateLimit-* del recurso compartido core.

Convenciones comunes

Paginación

Los endpoints paginados aceptan:

• pageSize: el valor predeterminado es 30 y el máximo es 100.
• pageToken: token opaco devuelto por la página anterior. No lo inspecciones ni lo construyas.

Las respuestas usan un campo de colección específico del recurso y nextPageToken. Este está vacío cuando no hay una página siguiente. Las respuestas de listas públicas no incluyen recuentos totales. Los tokens de página están vinculados al recurso y los filtros de los que proceden. Reinicia la paginación cuando cambien los filtros. Los tokens no vacíos no válidos o que no coincidan devuelven 400.

Envía el mismo pageSize en cada solicitud de una secuencia, incluidas las continuaciones. La mayoría de los endpoints de listado usan el pageSize enviado junto con un token de página para determinar el tamaño de esa página y mantienen el tamaño de la página anterior si se omite; así lo indican sus entradas de pageToken. Los demás difieren en lo que recuerda un token de página, por lo que, si usas un pageSize constante, obtendrás el mismo tamaño de página en todos los endpoints.

Errores

Los errores usan un cuerpo con el estilo de Google RPC:

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

Los estados HTTP habituales son 400, 401, 403, 404, 429, 500 y 503. Algunas operaciones de la base de datos de Git también devuelven 409 por conflictos en el estado del repositorio. Consulta Límites de uso para ver los encabezados de 429 y el comportamiento de reintento.

Usa el estado HTTP y code para distinguir entre errores. Considera message como texto para desarrolladores.

Un 404 nunca distingue entre un recurso que no existe y uno al que tu aplicación no puede acceder. Interprétalo como "no disponible para esta instalación" en lugar de como prueba de que el recurso no existe.

details contiene entradas tipadas: violaciones de campo de google.rpc.BadRequest cuando un argumento no es válido y una entrada google.rpc.RequestInfo en cada error. Origin puede añadir tipos de detalles en cualquier momento, así que ignora las entradas que tu integración no reconozca.

Cada respuesta de error incluye el ID de solicitud dos veces: en un encabezado de respuesta X-Request-ID y como una entrada google.rpc.RequestInfo en details. Origin devuelve el x-request-id que enviaste o genera uno si no envías ninguno. La entrada RequestInfo está presente incluso cuando message es un error interno opaco, así que incluye el ID de solicitud cuando te pongas en contacto con Cherri Code por una llamada fallida.

Las rutas sin coincidencia bajo /v1/origin y las solicitudes que usan el método incorrecto en una ruta conocida devuelven este mismo cuerpo en lugar de un error genérico del enrutador. El mensaje indica el método y la ruta, y nunca devuelve la cadena de consulta.

IDs

Los ID de recurso son cadenas opacas con un prefijo de tipo, como app_… para una aplicación e i_… para una instalación. Almacénalos y compáralos como cadenas completas. No los analices, no intentes deducir significado a partir de sus caracteres ni dependas de su orden.

Un ID no cambia durante toda la vida de su recurso, mientras que los nombres y los slugs sí pueden cambiar. Un repositorio conserva su ID aunque se le cambie el nombre, así que usa el ID como clave para los datos en caché en lugar de {ownerSlug}/{repoName}, y haz referencia al repositorio por su ID como se describe en Rutas de repositorio.

Rutas de repositorio

Las rutas con ámbito de repositorio usan el slug del propietario y el nombre del repositorio en el formato {ownerSlug}/{repoName}. Ambos segmentos se resuelven sin distinguir entre mayúsculas y minúsculas, por lo que cualquier combinación de estas identifica el repositorio. Las respuestas devuelven el nombre y el slug almacenados, no la combinación de mayúsculas y minúsculas que envió, y las URL de Git por HTTPS se resuelven de la misma forma. Compare los nombres de repositorio sin distinguir entre mayúsculas y minúsculas y consulte las mayúsculas y minúsculas canónicas en Obtener repositorio.

Todas las rutas con ámbito de repositorio también aceptan el ID estable del repositorio en lugar del par: envíe _ como slug del propietario y el ID como nombre del repositorio, como en GET /v1/origin/repos/_/REPO_ID. Consulte el ID en el campo id de Obtener repositorio. El valor especial _ no puede reclamarse como slug del propietario, por lo que las dos formas nunca entran en conflicto. En una solicitud de Connect o JSON, establezca ownerSlug en _ y name en el ID.

La forma con ID permanece tras un cambio de nombre, lo que la convierte en la forma estable de identificar un repositorio. No otorga nada por sí sola: después de que Origin resuelva el ID a un repositorio, su aplicación sigue necesitando el mismo ámbito en ese repositorio. Un ID al que su aplicación no puede acceder devuelve el mismo cuerpo 404 que un ID que no existe, por lo que una respuesta nunca confirma que un repositorio existe. Un ID malformado devuelve 400. Crear repositorio acepta solo un slug del propietario y rechaza _.

Referencias de recursos

Las instantáneas de recursos contienen los campos actuales del recurso. El contexto del contenedor utiliza referencias compactas en lugar de duplicar recursos completos:

• RepositoryReference identifica un repositorio.
• PullRequestReference identifica una pull request e incluye anidada la referencia a su repositorio.
• ThreadReference identifica el hilo que contiene un comentario de pull request.
• OriginActor identifica un actor público como una de las variantes user, app o serviceAccount. Hay exactamente una variante presente; lea la identidad de esa variante.

Ejecuciones de comprobación

Las aplicaciones informan los resultados de CI como suites de comprobación y ejecuciones de comprobación asociadas a un commit mediante Post Check Run y Batch Upsert Check Runs, y los consultan a través de los endpoints de Checks. Esta sección define los términos que comparten esos endpoints: qué intento es el actual, cómo Origin ordena e informa las escrituras, y cómo se comportan los timestamps y los plazos.

Intentos y el intento actual

Cada (actor, key, externalId) reportado sobre un commit es un intento de suite, y cada (suite, key, externalId) dentro de él es un intento de ejecución. Reutilizar un externalId actualiza ese intento en el mismo lugar; un externalId nuevo inicia un intento nuevo y conserva el anterior como historial. Los intentos sustituidos siguen siendo consultables por id mediante Get Check Suite y Obtener ejecución de comprobación.

Allí donde la API muestra las comprobaciones actuales de un commit —en List Check Suites For Commit, List Check Runs For Commit y en el estado de CI y las comprobaciones obligatorias del pull request—, Origin colapsa los intentos en dos pasos:

1. El intento de suite actual por (actor, key) es aquel cuyas ejecuciones actuales, tal como las selecciona el segundo paso, tienen el externalUpdatedAt más reciente; una suite sin ejecuciones se ordena por su createdAt. Los empates se resuelven por el createdAt de la suite y luego por su id, de más reciente a más antiguo.
2. Dentro de ese intento de suite, la ejecución actual para una key es la que tiene el externalUpdatedAt más reciente. Los empates se resuelven por createdAt y luego por id, de más reciente a más antiguo.

List Check Runs For Suite aplica el segundo paso a la suite que indiques. Una ejecución es la actual para su commit solo cuando su suite es el intento de suite actual del commit. Como el primer paso ordena intentos de suite completos, una ejecución publicada bajo un intento de suite sustituido queda fuera de las comprobaciones del commit mientras otro intento tenga un externalUpdatedAt más reciente; en cuanto su marca de tiempo sea la más reciente, su intento de suite pasa a ser el actual y se ocultan entonces las ejecuciones del otro intento.

Un intento cancelado no desplaza a uno superado. En cualquiera de los dos pasos, un intento cancelado queda por debajo de los demás intentos de su key si el intento no cancelado más reciente de esa key se superó. Una ejecución se considera superada cuando está completed con la conclusión success, neutral o skipped. Un intento de suite se considera superado cuando todas sus ejecuciones actuales se superaron, y cuenta como cancelado cuando todas sus ejecuciones actuales están completed, al menos una con la conclusión cancelled y el resto superadas. Cuando se solicita repetir el intento superado, los intentos cancelados cuyo externalUpdatedAt sea igual o posterior a la solicitud vuelven a ordenarse por sus marcas de tiempo. Un intento de suite cancelado más reciente sigue desplazando a uno más antiguo que no se superó por completo.

Una ejecución cuya repetición se ha solicitado mantiene su lugar como intento actual para su key y figura como pendiente hasta que la aplicación propietaria responda: consulta Rerequest Check Run.

Ordenar las escrituras

Origin ordena las publicaciones dirigidas a una misma ejecución, es decir, el mismo externalId y key dentro de la suite, según checkRun.externalUpdatedAt con precisión de milisegundos. Una publicación se aplica solo cuando su valor es igual o posterior al externalUpdatedAt almacenado de la ejecución, elevado a rerequestedAt mientras haya una nueva solicitud pendiente. Los valores iguales sí se aplican, por lo que gana la publicación más reciente, con dos excepciones que también se consideran obsoletas: una publicación queued o in_progress no puede reabrir una ejecución completed con la misma marca de tiempo, y una publicación con exactamente la marca de tiempo almacenada se ignora mientras rerequestedAt esté establecido. Un valor más reciente se aplica, incluso si reabre una ejecución completed, con una excepción que se considera obsoleta independientemente de su marca de tiempo: una publicación completed con la conclusión cancelled no puede reemplazar una ejecución completed cuya conclusión sea success, neutral o skipped.

Una publicación obsoleta igualmente se considera correcta. La respuesta es HTTP 200 con la suite y la ejecución almacenadas, no con los valores publicados, y el updatedAt de la ejecución no cambia. Cada ejecución publicada se devuelve como un par: checkRun, la ejecución almacenada después de la llamada, y outcome, lo que la escritura hizo con ella. Post Check Run devuelve el par en el nivel superior de su respuesta, junto a checkSuite. Batch Upsert Check Runs devuelve un par por cada ejecución publicada en results[], en el orden de la solicitud, de modo que un elemento del lote lleva el mismo resultado por ejecución que la llamada individual incluye directamente. Lee outcome, o cada results[].outcome, para saber qué hizo la escritura:

updatedAt no avanza en una publicación unchanged ni ignored_stale, por lo que no permite distinguirlas; solo outcome puede hacerlo. Interpreta un valor no reconocido como «la ejecución almacenada está en la respuesta; se desconoce si se escribió». En un lote, Origin aplica la regla a cada ejecución por separado: una ejecución obsoleta no hace fallar el lote, y results[] lleva la ejecución almacenada en la posición correspondiente con outcome ignored_stale.

En Batch Upsert Check Runs, el checkRuns[] de nivel superior está en desuso en favor de results[]. Se sigue rellenando con las mismas ejecuciones almacenadas y en el mismo orden, pero no incluye resultados; lee results[] en su lugar. Esto se aplica solo al lote: en Post Check Run, checkRun y outcome son los campos de nivel superior que debes leer.

Marcas de tiempo y plazos

Una publicación cuyo externalUpdatedAt, startedAt o completedAt se sitúe más de 60 segundos en el futuro devuelve InvalidArgument (HTTP 400). completedAt no puede ser anterior a startedAt cuando ambos aparecen en la misma publicación. deadlineAt no puede situarse más de 24 horas en el futuro.

Solo expira una ejecución in_progress. Una vez vencido su deadlineAt, un barrido periódico la completa con la conclusión timed_out, establece completedAt si la ejecución no lo tenía, borra deadlineAt y entrega repository.check_run.completed. La expiración se produce unos minutos después del plazo, no exactamente en él: el barrido se ejecuta aproximadamente cada 30 minutos de forma predeterminada, una configuración operativa que puede cambiar, así que no dependas de ese intervalo. Una ejecución queued nunca expira, ni tampoco una ejecución sin deadlineAt. Una publicación completed borra el plazo. Origin deja externalUpdatedAt intacto cuando agota el tiempo de una ejecución, por lo que una publicación posterior con un externalUpdatedAt más reciente sigue aplicándose a una ejecución expirada.

Limitaciones actuales

• El listado y la creación de repositorios en todo el espacio de nombres no forman parte de la API para partners. Descubre los repositorios mediante la instalación.
• La comparación de commits devuelve datos resumidos, en lugar de una lista de commits integrada. Los archivos modificados tienen su propio endpoint paginado, Listar archivos de comparación.
• Los hilos solo se pueden abordar para su resolución. No hay ningún endpoint que liste los hilos directamente; léelos en los comentarios que contienen.
• Los webhooks de push no incluyen una lista completa de commits.
• La fusión de pull requests es compatible con repositorios nativos de Origin. Los repositorios replicados se rechazan.
• Un repositorio replicado es de solo lectura para una instalación hasta que se convierta en una réplica saliente estable. Consulta Repositorios replicados.

Lista de verificación de implementación

• Almacena la clave privada de Ed25519 en un gestor de secretos y rota las claves de forma planificada. Consulta Generar una clave de firma de la app.
• Verifica el recibo de instalación en los callbacks de instalación y lee el ID de instalación y state de sus afirmaciones.
• Usa JWT de aplicación de corta duración y emite tokens de acceso de instalación justo a tiempo.
• Usa tokens de acceso de instalación, no JWT de aplicación, para las API con ámbito de repositorio, la escritura de comprobaciones y Git HTTPS.
• Solicita los ámbitos mínimos y el acceso al repositorio.
• Trata los tokens de página como opacos y reinicia la paginación cuando cambien los filtros.
• Mantén estables y legibles los valores de key de las comprobaciones. Usa un nuevo externalId inmutable para cada reintento y valores de externalUpdatedAt cada vez mayores para las actualizaciones.
• Lee outcome en cada respuesta de Post Check Run y cada results[].outcome en cada respuesta de Batch Upsert Check Runs; una publicación obsoleta devuelve 200 con la ejecución almacenada. Consulta Ejecuciones de comprobación.
• Verifica las firmas de los webhooks con el cuerpo sin procesar de la solicitud antes de analizarlo.
• Elimina las entregas duplicadas con webhook-id y procésalas de forma asíncrona después de devolver 2xx.
• Ignora los campos JSON desconocidos para garantizar la compatibilidad futura.
• Respeta los encabezados Retry-After y X-RateLimit-*. Usa Obtener límite de uso para supervisar los puntos restantes sin consumirlos.

Referencia de endpoints

Descarga la especificación de OpenAPI para consultar los esquemas completos de los componentes. El documento declara https://api.cursor.com como su servidor y un esquema de seguridad HTTP bearer bearerAuth, y cada operación incluye los códigos de respuesta que esa operación puede devolver, además de un ejemplo de solicitud y de respuesta. Cada operación también incluye una extensión x-origin-scopes: scopes contiene el ámbito que requiere la operación y tokenTypes contiene los tipos de credencial que acepta. Cada esquema de payload de webhook incluye una extensión x-origin-webhook-events que enumera los eventos que lo envían, y la superficie en versión preliminar incluye x-cursor-visibility: PREVIEW. Los parámetros de ruta tienen los mismos nombres que usan las URL: ownerSlug y repoName. Cada operación tiene un operationId único; cuando una misma operación responde a dos formas de URL, el id de la segunda forma lleva el sufijo _2, como en OriginService_GetRepoTarball_2.

Los fragmentos de JSON muestran valores de marcador de posición con la estructura del esquema. Las descripciones de los campos de respuesta reflejan el esquema de OpenAPI y el contrato actual de la plataforma.

Aplicaciones e instalaciones

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": "Publica el estado de CI en los pull request.",  "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"  ]}

Repositorios

cloneUrl es una URL HTTPS de clonación disponible solo en la salida. Obtener repositorio incluye cloneUrl.

Los partners descubren sus repositorios mediante Listar repositorios de la instalación de la aplicación. El listado de repositorios y su creación en todo el espacio de nombres no forman parte de la API para partners.

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}

Los endpoints de transición de réplicas están documentados en la Origin Migration API. Sincronizar réplica permanece en esta página.

Desvincular la réplica del repositorio

Consulta Desvincular la réplica del repositorio.

Obtener trabajo de transición de réplica

Consulta Obtener trabajo de transición de réplica.

Obtener trabajo activo de transición de réplica

Consulta Obtener trabajo activo de transición de réplica.

Forzar el cambio de la réplica del repositorio

Consulta Forzar el cambio de la réplica del repositorio.

Transición de la réplica del repositorio

Consulta Transición de la réplica del repositorio.

Comprobaciones

• La primera operación de crear o actualizar una ejecución crea automáticamente su suite.
• Las comprobaciones obligatorias se corresponden con la app que realiza la instalación, la key de la suite y, opcionalmente, la key de una ejecución. name solo se muestra y no se usa para establecer la correspondencia.
• Mantén los valores de key estables entre intentos y legibles para los usuarios, ya que la configuración de comprobaciones obligatorias se basa en ellos.
• Reutiliza externalId para actualizar un intento, lo que descarta el resultado anterior de ese intento; usa un externalId nuevo para reintentar, de modo que el intento anterior se conserve como historial.
• Usa checkRun.output para mostrar resultados legibles:
  • title: título breve del resultado, de hasta 255 caracteres.
  • summary: resumen principal en Markdown, de hasta 65 535 bytes UTF-8.
  • text: detalles ampliados en Markdown, de hasta 65 535 bytes UTF-8.
• Usa detailsUrl para enlazar a la página de resultados externa del proveedor.

Ejecuciones de comprobación define qué intento es el actual, cómo externalUpdatedAt ordena las escrituras y qué informa outcome, además de las reglas de marcas de tiempo y plazos que comparten estos 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"    }  ]}