Все запросы идут на https://api.coremind.ru, каждый маршрут начинается с префикса версии /v1. Другого адреса у публичного API нет.
Ключ и заголовок
Интеграция подписывает запрос одним из двух способов, оба — в заголовке Authorization: Bearer. Для своих скриптов и своего сервера — API-ключ cmk_…. Для приложения, которое работает от имени другого пользователя, — OAuth-токен доступа, выданный после его согласия; как его получить, описано на странице OAuth для приложений. Ничего другого передавать не нужно — ни идентификатор аккаунта, ни подпись тела.
Ещё один принимаемый канал — сессионная кука, и он не для интеграции: им пользуются страницы самого сервиса, у заголовка Bearer CORS закрыт, а изменяющий запрос по куке требует разрешённого Origin. В скачиваемой спеке ключ и кука объявлены как альтернативы, так что сгенерированный браузерный клиент видит и её.
Самая дешёвая проверка того, что ключ рабочий, — GET /v1/whoami: он отвечает тем, во что разрешился ключ, и ничего не стоит. Готовый вызов — первым шагом быстрого старта.
Свойства ключа
- Открытое значение показывается один раз, при создании, и больше никогда: у нас оно не хранится. Потерянный ключ не ищут ни в интерфейсе, ни через поддержку — его выпускают заново, а старый отзывают.
- Читаемый префикс
cmk_<id>остаётся в открытом виде: найденный в чужом репозитории ключ можно назвать и отозвать, не пересылая никому его целиком.
Ключ не работает из браузера
CORS для этого канала выключен намеренно: ключ не принимается из браузера и не должен попадать в клиентский JavaScript. Вызывайте API со своего сервера, скрипта или MCP-клиента.
Области доступа
Ниже — области, которые требует хотя бы один из опубликованных маршрутов. Это требования операций, а не полный словарь ключа: ключ может нести и области вне этого списка, и GET /v1/whoamiвернёт их все. Маршрут требует ровно ту, что указана в его x-required-scope, а не любую из списка; требования каждой операции видны в справочнике.
| Область | Что разрешает |
|---|---|
| me:read | Аккаунт вызывающего: тариф, баланс, бесплатные квоты, сам принципал. |
| models:read | Каталог моделей вместе с ценами и ограничениями. |
| generations:read | Чтение генераций — список, одна по идентификатору, пакетный статус и файлы результатов, в том числе шагов цепочки. |
| generations:write | Отправка генерации, её отмена и обращение в поддержку по ней. |
| library:read | Чтение библиотеки: загруженные референсы и папки. |
| library:write | — |
| billing:read | История списаний кредитов и статус подписки; баланс и тариф — в me:read. |
| support:read | Чтение своего треда поддержки. |
| support:write | Отправка сообщения в свой тред поддержки. |
| uploads:write | Подпись загрузки референса в наше хранилище. |
| workflows:read | Чтение цепочек, их версий и статусов запусков. |
| workflows:write | Создание, изменение и запуск цепочек; запуск списывает кредиты. |
Когда аутентификация не прошла
Ответ всегда приходит в общем конверте ошибки { error: { code, message, user_message, request_id } }, и ветвиться нужно по code. Здесь встречаются:
unauthorized— заголовка нет или он не разобран.invalid_api_key,api_key_expired,api_key_revoked— с самим ключом.invalid_token— OAuth-токен неизвестен, истёк или его разрешение отозвано.api_access_not_granted— у аккаунта нет доступа к публичному API.account_suspended— аккаунт заблокирован.insufficient_scope— ключу или токену не хватает области, которую требует маршрут.
HTTP-статус каждого кода и полный список остальных — на странице кодов ошибок.