HTTP 規約

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

作成と親 resource 内の一覧は所属先に従います。タスクと記録は案件配下、提案はプレイブック配下です。案件をまたぐタスク一覧とプレイブックをまたぐ提案一覧は、top-level の inbox view として残ります。Alias は (ownerId, alias) で namespace resource を識別するため top-level operation です。個人または管理可能な Workspace の各 namespace は、読めるプレイブックごとに1個の Alias を設定できます。プレイブック owner の Alias は公式として表示され、第三者 Alias は設定した namespace の owner 自身の context でだけ返されます。自分のタスクは assignedTo=me を使います。提案は view=sent で自分が送ったもの、view=inbox で自分が管理するプレイブック宛てのものを一覧でき、どちらも認証が必要です。

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 しないでください。記録は安定した (createdAt, id) 順序を使い、order=asc|desc を受け取ります。記録 filter は常に caller の live 案件 access との積です。

mutation

mutation body は idempotencyKey を持ちます。network failure または不確実な response 後に同一 request を再送するときだけ key を再利用します。案件・タスク mutation は expectedLockVersion、プレイブック publish は baseVersionId を含みます。不一致時は conflict を返し、client は fresh state を読んで intent を再構築できます。

タスク・案件 close request には new 記録を含められ、state transition と final durable output を同じ commit で保存できます。

error

429 と transient 5xx だけを bounded exponential backoff で retry します。validation、authorization、conflict response を自動 retry しません。conflict 時は current state を読み、人またはエージェントが判断してから新 mutation を発行します。