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-After | 429,以及使用相同 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。