Соглашения

Эти соглашения применяются ко всем endpoints API для разработчиков. Прочитав их один раз, можно оставить каждую страницу endpoint сосредоточенной на собственных параметрах и формах.

JSON повсюду

Тела запросов и ответов — это JSON (Content-Type: application/json), с одним исключением: загрузка документов использует multipart/form-data (смотрите endpoints документов Knowledge). Все временные метки — это строки ISO-8601 в UTC, например 2026-06-07T12:34:56Z.

Курсорная пагинация

Endpoints перечисления возвращают страницу с курсорной пагинацией, а не схему со смещением/номером страницы. Обёртка всегда имеет одну и ту же форму:

{
  "data": [ /* the items on this page */ ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImFndF8xMjMifQ"
}

Управляйте пагинацией двумя query-параметрами:

Считайте next_cursor непрозрачным значением — никогда не разбирайте, не конструируйте и не изменяйте его. Чтобы пройти все страницы, продолжайте запрашивать с next_cursor из предыдущего ответа, пока has_more не станет false:

# First page
curl "https://cuneiform.chat/api/developer/v1/agents?limit=50" \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"
 
# Next page
curl "https://cuneiform.chat/api/developer/v1/agents?limit=50&cursor=eyJpZCI6ImFndF8xMjMifQ" \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"

Искажённый курсор возвращает 400 invalid_request_error (invalid_cursor).

Идемпотентные запросы

Изменяющие запросы POST принимают необязательный заголовок Idempotency-Key, чтобы повторная попытка — после сетевой ошибки или тайм-аута — никогда не выполнила операцию дважды.

curl -X POST https://cuneiform.chat/api/developer/v1/agents \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c4b7a-2e3d-4f5a-8b6c-1d2e3f4a5b6c" \
  -d '{ "name": "Support Bot", "configuration": { "model": "gpt-4o-mini", "system_prompt": "You are helpful." } }'

Как это работает:

• Создавайте уникальный key для каждой логической операции (идеально подходит UUID) и отправляйте его с запросом.
• Повторный запрос, несущий тот же key в течение 24 часов, воспроизводит исходный сохранённый ответ вместо повторного выполнения операции.
• Keys ограничены вашей организацией.
• Через 24 часа key истекает; запрос с истёкшим key обрабатывается как новый.

Idempotency-Key учитывается на блокирующем пути запроса к agent, но игнорируется на потоковом пути (stream: true).

Ответы по принципу запрета по умолчанию

Тела ответов раскрывают только поля, описанные на странице каждого endpoint. Они никогда не включают внутренние идентификаторы, внутренние детали хранилища, строки провайдера/модели LLM или показатели стоимости. Если поля нет в описанной форме, API его не возвращает.

История изменений

v1 — это текущий, стабильный контракт. Изменения аддитивны — могут появиться новые поля и новые endpoints, но существующие поля никогда не удаляются и не переназначаются в рамках v1.