Authentication
Tất cả endpoint cần header Authorization: Bearer <token>. Có 2 dạng: • JWT cookie session (web app, set tự động sau khi đăng nhập) • API Key cw_sk_xxx (server-to-server, tạo tại /api-keys) API key có 4 scope: full | ai | data | automation. Endpoint /v1/chat /v1/messages /v1/embeddings yêu cầu scope "ai" hoặc "full".
POST /v1/chat/completions
OpenAI-compatible Chat Completions.
Request:
{
"messages": [{"role": "user", "content": "Hi"}],
"model": "auto", // optional · auto-route
"max_tokens": 200,
"temperature": 0.7
}
Response:
{
"id": "chatcmpl-...",
"object": "chat.completion",
"model": "<served_model>",
"choices": [{"index": 0, "message": {"role":"assistant","content":"..."}, "finish_reason": "stop"}],
"usage": {"prompt_tokens": N, "completion_tokens": M, "total_tokens": N+M},
"x_clawwits": {"provider":"...","cached":false,"ttft_ms":180}
}POST /v1/messages
Anthropic-compatible Messages API.
Request:
{
"system": "Bạn là trợ lý...", // optional
"messages": [{"role": "user", "content": "..."}],
"max_tokens": 1024,
"temperature": 0.7
}
Response:
{
"id": "msg_...",
"type": "message",
"role": "assistant",
"content": [{"type":"text","text":"..."}],
"usage": {"input_tokens":N, "output_tokens":M, "cache_read_input_tokens":K},
"stop_reason": "end_turn"
}POST /v1/embeddings
OpenAI-compatible embeddings — 1024-dim L2-normalized vector.
Request:
{
"input": "single string" | ["batch", "of", "strings"],
"model": "auto"
}
Response:
{
"object": "list",
"data": [{"object":"embedding","index":0,"embedding":[...1024 floats...]}],
"usage": {"prompt_tokens": N, "total_tokens": N}
}GET /v1/wits/balance
Wits Token balance hiện tại.
Response:
{
"userId": "uuid",
"available": 2999986, // tokens chưa reserve
"reserved": 0, // tokens đang dùng
"lifetimeUsed": 14
}Rate limits
Theo tier (req/phút): free_trial 30 starter 300 plus 1,000 pro 5,000 power 20,000 max 100,000 enterprise custom (1M+) 429 Too Many Requests + retry-after-ms khi vượt.
Error codes
400 invalid_request - missing/malformed body 400 isv_blocked - prompt injection / banned content 401 unauthorized - missing or invalid token 402 insufficient_wits - balance không đủ; topup tại /pricing 403 forbidden / insufficient_scope - scope API key không đủ 404 not_found 429 rate_limited - retry sau retryAfterMs 502 router_error - Zeni Cloud Lop 03 fail