Visão geral da API
URL base, versionamento, convenções de requisição e resposta, headers e IDs da API pública da Dcision.
A API pública roda decisões publicadas sobre um estado e devolve respostas tipadas, confiança e uma ação. Endpoints de leitura, com as mesmas API keys, listam as decisões do workspace e os contratos delas, a conta e as execuções recentes. Uma decisão também pode rodar a partir de uma URL de webhook secreta, sem API key, e agentes podem usar tudo isso pelo servidor MCP.
Base URL https://api.dcision.io
Version /v1 (in the path)
Auth Authorization: Bearer dcs_live_… | dcs_test_…
Format JSON in, JSON outEndpoints
| Método e caminho | Descrição |
|---|---|
POST /v1/decisions/{slug} | Roda a versão ativa de uma decisão. |
GET /v1/decisions | As decisões do workspace: slug, nome, status e versão ativa. |
GET /v1/decisions/{slug} | O que a versão ativa de uma decisão aceita e responde: state schema, perguntas, ações e um estado de exemplo. |
GET /v1/decisions/{slug}/openai-live | As perguntas da versão ativa como delegação do GPT-Live, para a voz em tempo real da OpenAI. |
POST /v1/decisions/{slug}/openai-live/answers | Aplica as respostas de uma sessão do GPT-Live: políticas, destinos e o log de execuções, cobrado como uma execução. |
GET /v1/me | O workspace da chave, a chave, o plano e o uso do período atual. |
GET /v1/executions | Execuções recentes com respostas, ação e métricas — nunca as entradas. |
POST /v1/hooks/{token} | Roda uma decisão a partir da URL de webhook secreta dela — sem API key; opcionalmente assinada com um segredo whsec_. |
POST /mcp | O servidor MCP para agentes de IA — as mesmas chaves, limites e cobrança. |
GET /openapi.json | A descrição OpenAPI 3.1 da API pública, incluindo o evento de webhook decision.completed. Sem autenticação. |
GET /health | Saúde do serviço: { "status": "ok" }. Sem autenticação. |
Decisões, versões, destinos, API keys, membros e cobrança são gerenciados no app. Os endpoints do próprio app exigem uma sessão de usuário e recusam API keys com 403 FORBIDDEN. Os webhooks vão no sentido contrário — da Dcision para você — veja Eventos de webhook.
Requisições
- Só HTTPS, para
https://api.dcision.io. - Body JSON com
Content-Type: application/json, UTF-8, de no máximo 128 KB — 1 MB emPOST /mcp, cujas ferramentas podem levar um decision schema inteiro (o estado continua limitado a 128 KB), e 32 MB emPOST /v1/decisions/{slug}e no webhook de entrada, cujo estado pode levar arquivos — o webhook de entrada também aceitamultipart/form-data. Veja Limites. - Só no servidor: API keys são segredos — chame a API a partir do seu backend, de um worker ou de um runtime de agente, nunca de um navegador ou de um app mobile.
| Header de requisição | Obrigatório | Descrição |
|---|---|---|
Authorization | Sim | Bearer <API key> — veja Autenticação. |
Content-Type | Sim | application/json. |
Idempotency-Key | Não | Torna os retries seguros — veja Idempotência. |
X-Request-ID | Não | O seu ID de correlação: 1–128 caracteres de A–Z a–z 0–9 . _ : -. Caso contrário, a Dcision gera um. |
Respostas
-
JSON com campos em snake_case; as chaves das suas perguntas são usadas como estão.
-
Códigos de status HTTP padrão:
200em caso de sucesso,4xxpara problemas na requisição,5xxpara problemas do lado da Dcision ou do engine. -
Os erros sempre têm o mesmo formato — veja Erros:
{ "error": { "code": "INVALID_STATE", "message": "Field company_size must be a number.", "request_id": "req_7Gm2xPq9Lk4sVt1RbN8w" } }
| Header de resposta | Quando | Descrição |
|---|---|---|
X-Request-ID | Sempre | O seu X-Request-ID, ou um ID req_… gerado. Cite-o quando falar com o suporte. |
X-RateLimit-Limit | Chamadas autenticadas | Requisições permitidas por minuto para o seu workspace — decisões e leituras têm janelas separadas. |
X-RateLimit-Remaining | Chamadas autenticadas | Requisições restantes na janela atual. |
X-RateLimit-Reset | Chamadas autenticadas | Quando a janela reinicia, em segundos Unix. |
Retry-After | 429, e 409 enquanto uma requisição com o mesmo Idempotency-Key ainda está rodando | Segundos a esperar antes de tentar de novo. |
Idempotent-Replayed | Replays | true quando a resposta é um replay guardado. |
IDs
Os IDs são um prefixo seguido de 20 letras e dígitos:
| Prefixo | Identifica | Onde você o vê |
|---|---|---|
dec_ | uma decisão | decision_id nas respostas, a página da decisão no app |
exec_ | uma execução (uma rodada) | execution_id nas respostas, Execuções, GET /v1/executions |
key_ | uma API key | api_key.id em GET /v1/me |
dlv_ | uma entrega de um destino | delivery_id nas respostas, o header Dcision-Delivery, o id de um evento de webhook |
req_ | uma requisição | X-Request-ID, request_id nos erros |
Estabilidade
Os formatos de requisição e resposta de /v1 são estáveis; novos campos só são adicionados — como scores, composites e as contagens de tokens em metrics na v0.2, e destinations na v0.3 —, então ignore os campos que você não conhece. O contrato da sua decisão — as chaves de result e os tipos delas — só muda quando você publica uma nova versão, e o version da resposta diz qual versão respondeu.
A API é uma única chamada HTTPS a partir de qualquer linguagem. Os SDKs oficiais para TypeScript e Python acrescentam retries seguros, destinos de função e verificação de webhooks — compile-os a partir do código-fonte até que sejam publicados no npm e no PyPI. Para o terminal e o CI, use a CLI.
Segurança e limites dos destinos
Como a Dcision protege as requisições de saída — só https, proteção contra SSRF, sem redirecionamentos, segredos — o que cada tipo envia e guarda, quem configura o quê, e todos os limites.
Autenticação
Autentique com API keys Bearer (dcs_live_ e dcs_test_) — crie, guarde, troque e revogue as chaves — e saiba onde elas funcionam.