Обзор API

Базовый URL, версионирование, соглашения о запросах и ответах, заголовки и идентификаторы публичного API Dcision.

Публичный API выполняет опубликованные решения на заданном состоянии (state) и возвращает типизированные ответы, уверенность и действие. Эндпоинты чтения с теми же API-ключами показывают решения рабочего пространства и их контракты, его аккаунт и недавние выполнения. Решение также можно запустить через секретный URL вебхука, без API-ключа, а агенты могут пользоваться всем этим через MCP-сервер.

Base URL   https://api.dcision.io
Version    /v1 (in the path)
Auth       Authorization: Bearer dcs_live_… | dcs_test_…
Format     JSON in, JSON out

Эндпоинты

Метод и путьОписание
POST /v1/decisions/{slug}Выполнить активную версию решения.
GET /v1/decisionsРешения рабочего пространства: slug, название, статус и активная версия.
GET /v1/decisions/{slug}Что принимает и на что отвечает активная версия решения: схема state, вопросы, действия и пример state.
GET /v1/decisions/{slug}/openai-liveВопросы активной версии в виде делегирования GPT-Live для голосового режима реального времени OpenAI.
POST /v1/decisions/{slug}/openai-live/answersПрименить ответы сессии GPT-Live: политики, назначения и журнал выполнений, тарифицируется как запуск.
GET /v1/meРабочее пространство ключа, сам ключ, тариф и использование за текущий период.
GET /v1/executionsНедавние выполнения с ответами, действием и метриками — без входных данных.
POST /v1/hooks/{token}Запустить решение через его секретный URL вебхука — без API-ключа; по желанию с подписью секретом whsec_.
POST /mcpMCP-сервер для ИИ-агентов — те же ключи, лимиты и тарификация.
GET /openapi.jsonОписание публичного API в формате OpenAPI 3.1, включая событие вебхука decision.completed. Без аутентификации.
GET /healthСостояние сервиса: { "status": "ok" }. Без аутентификации.

Решения, версии, назначения, API-ключи, участники и оплата управляются в приложении. Собственные эндпоинты приложения требуют пользовательскую сессию и отклоняют API-ключи с 403 FORBIDDEN. Вебхуки идут в обратном направлении — от Dcision к вам, — см. События вебхуков.

Запросы

  • Только HTTPS, на https://api.dcision.io.
  • JSON-тело с Content-Type: application/json, UTF-8, не более 128 KB — 1 MB для POST /mcp, чьи инструменты могут передавать целую схему решения (state по-прежнему ограничен 128 KB), и 32 MB для POST /v1/decisions/{slug} и триггера вебхука, чей state может содержать файлы, — триггер вебхука также принимает multipart/form-data. См. Ограничения.
  • Только на сервере: API-ключи — это секреты; вызывайте API со своего бэкенда, воркера или среды выполнения агента, никогда — из браузера или мобильного приложения.
Заголовок запросаОбязателенОписание
AuthorizationДаBearer <API key> — см. Аутентификация.
Content-TypeДаapplication/json.
Idempotency-KeyНетДелает повторы безопасными — см. Идемпотентность.
X-Request-IDНетВаш ID корреляции: 1–128 символов из A–Z a–z 0–9 . _ : -. Иначе Dcision сгенерирует его.

Ответы

  • JSON с полями в snake_case; ключи ваших вопросов используются как есть.

  • Стандартные коды HTTP: 200 при успехе, 4xx при проблемах с запросом, 5xx при проблемах на стороне Dcision или движка.

  • Ошибки всегда имеют одинаковую форму — см. Ошибки:

    { "error": { "code": "INVALID_STATE", "message": "Field company_size must be a number.", "request_id": "req_7Gm2xPq9Lk4sVt1RbN8w" } }
Заголовок ответаКогдаОписание
X-Request-IDВсегдаВаш X-Request-ID или сгенерированный ID req_…. Указывайте его при обращении в поддержку.
X-RateLimit-LimitАутентифицированные вызовыСколько запросов в минуту разрешено вашему рабочему пространству — у решений и чтений отдельные окна.
X-RateLimit-RemainingАутентифицированные вызовыСколько запросов осталось в текущем окне.
X-RateLimit-ResetАутентифицированные вызовыКогда окно сбросится, в секундах Unix.
Retry-After429, а также 409, пока запрос с тем же Idempotency-Key ещё выполняетсяСколько секунд подождать перед повтором.
Idempotent-ReplayedПовторыtrue, когда ответ — сохранённый повтор.

Идентификаторы

Идентификаторы — это префикс, за которым следуют 20 букв и цифр:

ПрефиксЧто обозначаетГде вы его видите
dec_решениеdecision_id в ответах, страница решения в приложении
exec_выполнение (один запуск)execution_id в ответах, Выполнения, GET /v1/executions
key_API-ключapi_key.id в GET /v1/me
dlv_доставка в назначениеdelivery_id в ответах, заголовок Dcision-Delivery, id события вебхука
req_запросX-Request-ID, request_id в ошибках

Стабильность

Формы запросов и ответов /v1 стабильны; новые поля только добавляются — например, scores, composites и счётчики токенов в metrics в v0.2 и destinations в v0.3, — поэтому игнорируйте незнакомые поля. Контракт вашего решения — ключи result и их типы — меняется, только когда вы публикуете новую версию, а поле version в ответе указывает, какая версия ответила.

API — это один HTTPS-вызов из любого языка. Официальные SDK для TypeScript и Python добавляют безопасные повторы, функции-назначения и проверку вебхуков — собирайте их из исходников, пока они не опубликованы в npm и PyPI. Для терминала и CI используйте CLI.

На этой странице