Conventions

The whole API follows these conventions. Read this page = read most endpoints.

Naming

Style	Used in
kebab-case	URL paths (`/v1/knowledge-bases`)
snake_case	JSON fields + query params (`user_id`, `created_at`)

List endpoints support pagination uniformly:

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

Parameter	Description
`limit`	Page size, default 20, max 100
`cursor`	The previous response's `next_cursor`

Response format:

{
  "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

- prefix = descending.

All ISO 8601 + UTC:

2026-05-08T14:30:00Z

User time zones are accepted in requests (auto-converted):

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

Write operations support an idempotency key (avoid duplicate triggers):

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

Within 24 hours, the same key is treated as the same request and returns the same result.

Endpoints that support SSE (e.g. Agent chat, Workflow run):

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

Each chunk:

event: message
data: {"delta": "Hello"}

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

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

Every response contains:

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