Origin API
Origin находится на раннем этапе бета-тестирования и может измениться. При обновлении интеграции сверяйтесь со спецификацией OpenAPI.
Origin — платформа Cursor для разработки кода. Её публичный REST API позволяет приложениям и инструментам работать с репозиториями Origin, коммитами, проверками, pull request и установками приложений.
- Origin Apps проходят аутентификацию с помощью JWT приложений и токенов доступа установки. См. раздел Аутентификация.
- Полную спецификацию OpenAPI с подробными схемами и примерами можно посмотреть здесь.
- Агенты могут загрузить индекс llms.txt или полную справочную документацию в формате Markdown по адресу llms-full.txt.
Обзор
Приложения Origin используют модель согласия на установку в стиле OAuth и модель аутентификации в стиле GitHub App:
- Приложение подписывает краткосрочный EdDSA JWT своим приватным ключом Ed25519.
- Приложение обменивает этот JWT и идентификатор установки на краткосрочный токен доступа установки (
oit_…). - Токен установки обращается к API репозиториев и аутентифицирует Git по HTTPS в пределах одобренных для установки репозиториев и областей доступа.
- Origin отправляет подписанные доставки вебхука на зарегистрированный URL вебхука приложения.
Базовый URL
https://api.cursor.com/v1/originПути к конечной точке в справочнике включают полный префикс /v1/origin.
Соглашения протокола
Для запросов и ответов используется application/json. В именах полей JSON используется camelCase. Метки времени указываются в виде строк RFC 3339. 64-битные целые числа Protobuf, включая номера pull request и номера версий, кодируются как строки JSON.
Ответы содержат поля со значениями по умолчанию, а не опускают их, поэтому логическое значение false, число 0, пустая строка и пустой массив присутствуют в теле. Считывайте само значение, а не трактуйте отсутствующий ключ как значение по умолчанию. Поля, описанные в документации как отсутствующие или опускаемые, являются необязательными в контракте и не включаются в тело, если не заданы.
Начало работы
Доступ к Origin
- Откройте Origin на cursor.com/codebase.
- Управляйте настройками приложений на cursor.com/codebase/settings/apps.
- Создайте ключ подписи приложения и зарегистрируйте только открытый ключ.
Origin CLI
Установите Origin CLI и войдите в систему:
curl -fsSL https://downloads.cursor.com/origin/install.sh | shorigin auth loginКлонируйте существующий репозиторий:
origin repo clone '{ownerSlug}/{repoName}'# или напрямую через gitgit clone 'https://origin.cursor.com/{ownerSlug}/{repoName}.git'Apps клонируют через аутентификацию Git по HTTPS с токеном доступа установки, а не с учётными данными пользователя.
Установка
Попросите администратора рабочей области клиента перейти по ссылке:
https://cursor.com/codebase/apps/install ?client_id=APP_ID &scope=SPACE_SEPARATED_SCOPES &redirect_uri=REGISTERED_CALLBACK &state=RANDOM_ANTI_FORGERY_VALUE &summary=SHORT_REASON_FOR_ACCESS &include_granted_scopes=true| Параметр | Обязательный | Описание |
|---|---|---|
client_id | Да | идентификатор приложения Origin. |
scope | Да | Области доступа, разделённые пробелами. repository:metadata:read добавляется автоматически. |
redirect_uri | Да при установке по инициативе партнёра | Точный зарегистрированный URI обратного вызова. |
state | Настоятельно рекомендуется | Случайное значение для защиты от подделки, дублируемое в качестве утверждения state в квитанции об установке. Создайте его перед перенаправлением и проверьте утверждение в обратном вызове. |
summary | Нет | Краткое пояснение, отображаемое при предоставлении согласия. |
include_granted_scopes | Нет | Если true, сохраняет существующие разрешения и запрашивает только дополнительные. |
Администратор рабочей области выбирает целевого владельца, одобренные области доступа, а также все репозитории или выбранные репозитории. Доступ к репозиториям контролирует клиент, а не приложение.
После одобрения Origin перенаправляет на зарегистрированный обратный вызов:
https://ci.example.com/origin/callback?installation_receipt=RECEIPT_JWTПроверьте квитанцию об установке, затем сохраните идентификатор установки из утверждения sub. Он понадобится при выпуске токена доступа установки.
Установки используют один из двух режимов выбора репозиториев:
all: установка может получать доступ ко всем репозиториям, принадлежащим выбранной цели.selected: установка может получать доступ только к репозиториям, выбранным администратором рабочей области.
Оба режима распространяются на зеркалированные репозитории и нативные репозитории Origin, поэтому зеркало появляется в GET /installation/repos и его можно выбрать. Зеркало доступно только для чтения, пока не станет стабильным исходящим зеркалом: см. Зеркалированные репозитории.
Используйте GET /installation/repos с токеном установки, чтобы узнать, какие репозитории доступны для этой установки. Конечные точки App JWT позволяют выводить список установок приложения, просматривать их и удалять. Удаление установки предотвращает выпуск новых токенов.