API 概览

Dcision 公共 API 的基础 URL、版本管理、请求与响应约定、请求头和 ID。

公共 API 在给定状态上运行已部署的决策,并返回类型化的回答、置信度和行动。读取类端点使用相同的 API 密钥,可以列出工作区的决策及其契约、账户和最近的执行记录。决策也可以通过秘密的 webhook 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}决策当前生效版本接受什么、回答什么:状态 schema、问题、行动和示例状态。
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}通过决策的秘密 webhook URL 运行它——无需 API 密钥;可选用 whsec_ 密钥签名。
POST /mcp面向 AI 智能体的 MCP 服务器——相同的密钥、限制和计费。
GET /openapi.json公共 API 的 OpenAPI 3.1 描述,包括 decision.completed webhook 事件。无需身份验证。
GET /health服务健康状态:{ "status": "ok" }。无需身份验证。

决策、版本、目的地、API 密钥、成员和计费都在应用中管理。应用自身的端点需要用户会话,并会以 403 FORBIDDEN 拒绝 API 密钥。Webhook 的方向相反——从 Dcision 发往你——参见 Webhook 事件。

请求

  • 仅限 HTTPS,发往 https://api.dcision.io。
  • JSON 请求体,使用 Content-Type: application/json、UTF-8,最大 128 KB——POST /mcp 为 1 MB,因为其工具可以携带完整的决策 schema(状态仍限制为 128 KB);POST /v1/decisions/{slug} 和 webhook 触发器 为 32 MB,因为其状态可以携带文件——webhook 触发器还接受 multipart/form-data。参见限制。
  • 仅限服务器端:API 密钥是机密——请从你的后端、worker 或智能体运行时调用 API,切勿从浏览器或移动应用中调用。
请求头必填描述
Authorization是Bearer <API key>——参见身份验证。
Content-Type是application/json。
Idempotency-Key否让重试变得安全——参见幂等性。
X-Request-ID否你的关联 ID:1–128 个字符,取自 A–Z a–z 0–9 . _ : -。否则由 Dcision 生成一个。

响应

  • 使用 snake_case 字段的 JSON;你的问题键按原样使用。

  • 标准 HTTP 状态码:成功时为 200,请求有问题时为 4xx,Dcision 或引擎一侧出问题时为 5xx。

  • 错误始终具有相同的结构——参见错误:

    { "error": { "code": "INVALID_STATE", "message": "Field company_size must be a number.", "request_id": "req_7Gm2xPq9Lk4sVt1RbN8w" } }
响应头何时出现描述
X-Request-ID始终你的 X-Request-ID,或生成的 req_… ID。联系支持时请提供它。
X-RateLimit-Limit经过身份验证的调用你的工作区每分钟允许的请求数——决策与读取使用各自独立的窗口。
X-RateLimit-Remaining经过身份验证的调用当前窗口中剩余的请求数。
X-RateLimit-Reset经过身份验证的调用窗口重置的时间,以 Unix 秒表示。
Retry-After429,以及使用相同 Idempotency-Key 的请求仍在运行时的 409重试前需要等待的秒数。
Idempotent-Replayed重放当响应是已存储的重放时为 true。

ID

ID 由前缀加 20 个字母和数字组成:

前缀标识在哪里看到
dec_一个决策响应中的 decision_id,应用中的决策页面
exec_一次执行(一次运行)响应中的 execution_id、执行记录、GET /v1/executions
key_一个 API 密钥GET /v1/me 中的 api_key.id
dlv_目的地的一次投递响应中的 delivery_id、Dcision-Delivery 请求头、webhook 事件的 id
req_一个请求X-Request-ID、错误中的 request_id

稳定性

/v1 的请求和响应结构是稳定的;只会新增字段——例如 v0.2 中的 scores、composites 以及 metrics 中的 token 计数,v0.3 中的 destinations——因此请忽略你不认识的字段。你的决策契约——result 的键及其类型——只有在你部署新版本时才会改变,响应中的 version 会告诉你是哪个版本作答的。

该 API 只需一次 HTTPS 调用,任何语言都可以使用。官方的 TypeScript 和 Python SDK 增加了安全重试、函数目的地和 webhook 验证——在它们发布到 npm 和 PyPI 之前,请从源码构建。在终端和 CI 中,请使用 CLI。

本页内容