Skip to Content
Справочник APIВведение

Справочник API

REST API для разработчиков Cuneiform Chat позволяет вашим разработчикам управлять документами knowledge, создавать и настраивать agents, а также запускать agents программно — те же возможности, что предоставляет панель администратора, доступные через защищённую учётными данными версионированную поверхность HTTP.

Этот справочник описывает публичный контракт /v1: каждый endpoint, его параметры, пример запроса и точную форму ответа.

Базовый URL

Все endpoints находятся под единым версионированным базовым URL:

https://cuneiform.chat/api/developer/v1

Полный путь endpoint — это базовый URL плюс путь, показанный на каждой странице. Например, GET /agents это:

https://cuneiform.chat/api/developer/v1/agents

Версионирование

API версионируется в префиксе URL (/v1). Нет версионирования на основе заголовков или дат — версия, которую вы вызываете, это версия в пути. Контракт /v1 стабильный: поля только добавляются, никогда не удаляются и не переназначаются, а новая мажорная версия (если она когда-либо понадобится) будет выпущена под новым префиксом. Базовую точку версии смотрите в заметке Истории изменений.

Аутентификация в одной строке

Каждый запрос аутентифицируется с помощью API key разработчика (cuk_…), отправляемого как токен Bearer:

Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx

Key сопоставляется с вашей организацией и с предоставленными ей scopes — id организации передавать не нужно. Полный контракт смотрите в разделах Аутентификация и API Keys.

Ваш первый вызов

  1. Создайте key. В панели администратора откройте консоль разработчика по адресу /org/developer-api, создайте key и скопируйте секрет (он показывается только один раз — смотрите API Keys).
  2. Вызовите API. Получите список ваших agents:
curl https://cuneiform.chat/api/developer/v1/agents \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"

Успешный ответ — это страница с курсорной пагинацией:

{
  "data": [
    {
      "id": "agt_123",
      "name": "Support Bot",
      "status": "active"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Как читать этот справочник

Каждый endpoint описан кратким описанием в одну строку, таблицей Параметры (path, query, header и body), примером запроса curl и примером ответа. Требуемый scope, статус успеха и соответствующие категории ошибок указаны для каждого endpoint.

СтраницаЧто охватывает
АутентификацияДва способа предъявить key; во что сопоставляется key
API KeysСоздание, перечисление, ротация и отзыв keys; среды; таксономия scopes
СоглашенияКурсорная пагинация, идемпотентные запросы, тип содержимого, временные метки
ОшибкиКонверт ошибки и семь категорий ошибок
Ограничения частотыЗаголовки RateLimit-* и контракт 429
KnowledgeДокументы (загрузка, статус, поиск, удаление) и организация (папки, tags)
AgentsСоздание, перечисление, обновление, удаление, восстановление и настройка agents
Запрос к AgentЗапуск agent — блокирующий JSON или потоковый ответ SSE

Спецификация OpenAPI

Полный контракт также публикуется как написанная вручную спецификация OpenAPI 3.1, openapi.yaml, доступная для скачивания рядом с этим справочником. Это единственный источник истины, относительно которого написаны эти страницы — каждое поле схемы это поле, которое API действительно возвращает, и ни одно внутреннее поле не появляется.

Право доступа

REST API для разработчиков доступен на Starter и выше. Организации на Trial не могут создавать keys; попытка возвращает 403 tier_error.

Last updated on
Аутентификация