约定 · Evose

API 全站遵循以下约定。读懂这一页 = 读懂大部分端点。

命名

风格	应用于
kebab-case	URL 路径（`/v1/knowledge-bases`)
snake_case	JSON 字段 + 查询参数（`user_id`、`created_at`)

列表端点统一支持分页:

GET /v1/agents?limit=20&cursor=eyJpZCI6...

参数	说明
`limit`	单页条数，默认 20，最大 100
`cursor`	上次响应的 `next_cursor`

响应格式:

{
  "data": [...],
  "next_cursor": "eyJpZCI6...",
  "has_more": true
}

GET /v1/agents?workspace_id=ws-001&status=active&created_after=2026-01-01

GET /v1/agents?sort=-created_at,name

- 前缀 = 倒序。

全部 ISO 8601 + UTC:

2026-05-08T14:30:00Z

请求中也接受用户时区（自动转换):

{ "schedule_at": "2026-05-08T22:30:00+08:00" }

写操作支持幂等键（避免重复触发):

POST /v1/workflows/wf-001/runs
Idempotency-Key: 2c8d3f1a-..

24 小时内相同 key 视为同一请求，返回相同结果。

支持 SSE 的端点（如 Agent chat、Workflow run):

POST /v1/agents/<id>/chat
Accept: text/event-stream

每个 chunk:

event: message
data: {"delta": "你好"}

event: usage
data: {"tokens_in": 8, "tokens_out": 12}

event: done
data: {"finish_reason": "stop"}

每个响应都含:

{
  "request_id": "req-xxxxxxxx",
  "data": { ... },
  "meta": {
    "version": "v1",
    "deprecated_warnings": []
  }
}