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 out

Endpoints

Método e caminhoDescrição
POST /v1/decisions/{slug}Roda a versão ativa de uma decisão.
GET /v1/decisionsAs 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-liveAs 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/answersAplica 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/meO workspace da chave, a chave, o plano e o uso do período atual.
GET /v1/executionsExecuçõ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 /mcpO servidor MCP para agentes de IA — as mesmas chaves, limites e cobrança.
GET /openapi.jsonA descrição OpenAPI 3.1 da API pública, incluindo o evento de webhook decision.completed. Sem autenticação.
GET /healthSaú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 em POST /mcp, cujas ferramentas podem levar um decision schema inteiro (o estado continua limitado a 128 KB), e 32 MB em POST /v1/decisions/{slug} e no webhook de entrada, cujo estado pode levar arquivos — o webhook de entrada também aceita multipart/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çãoObrigatórioDescrição
AuthorizationSimBearer <API key> — veja Autenticação.
Content-TypeSimapplication/json.
Idempotency-KeyNãoTorna os retries seguros — veja Idempotência.
X-Request-IDNãoO 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: 200 em caso de sucesso, 4xx para problemas na requisição, 5xx para 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 respostaQuandoDescrição
X-Request-IDSempreO seu X-Request-ID, ou um ID req_… gerado. Cite-o quando falar com o suporte.
X-RateLimit-LimitChamadas autenticadasRequisições permitidas por minuto para o seu workspace — decisões e leituras têm janelas separadas.
X-RateLimit-RemainingChamadas autenticadasRequisições restantes na janela atual.
X-RateLimit-ResetChamadas autenticadasQuando a janela reinicia, em segundos Unix.
Retry-After429, e 409 enquanto uma requisição com o mesmo Idempotency-Key ainda está rodandoSegundos a esperar antes de tentar de novo.
Idempotent-ReplayedReplaystrue quando a resposta é um replay guardado.

IDs

Os IDs são um prefixo seguido de 20 letras e dígitos:

PrefixoIdentificaOnde você o vê
dec_uma decisãodecision_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 keyapi_key.id em GET /v1/me
dlv_uma entrega de um destinodelivery_id nas respostas, o header Dcision-Delivery, o id de um evento de webhook
req_uma requisiçãoX-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.

Nesta página