Обзор 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 /mcp | MCP-сервер для ИИ-агентов — те же ключи, лимиты и тарификация. |
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-After | 429, а также 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.
Безопасность и лимиты назначений
Как Dcision защищает исходящие запросы — только https, защита от SSRF, без редиректов, секреты, — что отправляет и хранит каждый тип назначения, кто что может настраивать, и все лимиты назначений.
Аутентификация
Аутентификация с помощью API-ключей Bearer (dcs_live_ и dcs_test_) — как их создавать, хранить, ротировать и отзывать — и где они работают.