HTTP 規約
product endpoint map、request 規約、pagination、conflict、error です。
protected /v1 endpoint は Authorization: Bearer <access-token> と JSON request body を受け取ります。API は public request shape を validate し、caller・workspace context を resolve し、domain service へ delegation します。API 自身は product storage を所有しません。
core endpoint map
| domain | 主な endpoint |
|---|---|
| Playbook | GET/POST /v1/playbooks、GET/DELETE /v1/playbooks/:id、Version、ACL、star、share-token route |
| Alias | GET/PUT /v1/aliases、DELETE /v1/aliases/:alias |
| Case | GET/POST /v1/cases、GET/PATCH /v1/cases/:id、assignee、ACL、close、reopen |
| Task | GET/POST /v1/tasks、update、assignee、close、reopen |
| Record | GET/POST /v1/records |
| Suggestion | GET/POST /v1/suggestions、get、update、resolve |
| Administration | workspace、workspace member、project、project member、credit、CLI・MCP token |
Task と Record は caseId を持つ top-level resource で、API を /v1/cases/:id の下に重複させません。assigned-Task inbox と Case 横断 Record feed を first-class に扱えます。
context と pagination
対応する administrative endpoint は query parameter で workspaceId を受け取ります。product-domain route は bearer credential から actor context を解決します。local CLI で選択した workspace が raw HTTP request にも適用されると仮定しないでください。
list operation は pageSize と opaque な cursor を使います。cursor をそのまま保持し、生成・decode しないでください。Record は安定した (createdAt, id) 順序を使い、order=asc|desc を受け取ります。Record filter は常に caller の live Case access との積です。
mutation
mutation body は idempotencyKey を持ちます。network failure または不確実な response 後に同一 request を再送するときだけ key を再利用します。Case・Task mutation は expectedLockVersion、Playbook publish は baseVersionId を含みます。不一致時は conflict を返し、client は fresh state を読んで intent を再構築できます。
Task・Case close request には new Record を含められ、state transition と final durable output を同じ commit で保存できます。
error
| status | 意味 |
|---|---|
400 |
不正 parameter、query、JSON、unsupported value、request-schema validation failure |
401 |
bearer credential の missing、expired、invalid |
402 |
resolved context の credit 不足 |
403 |
authenticated だが operation 権限なし |
404 |
resource が存在しない、または意図的に hidden |
409 |
base Version、lock Version、lifecycle、uniqueness conflict |
429 |
rate limit。backoff 後に retry |
5xx |
server または upstream failure |
429 と transient 5xx だけを bounded exponential backoff で retry します。validation、authorization、conflict response を自動 retry しません。conflict 時は current state を読み、人またはエージェントが判断してから新 mutation を発行します。