パック

再利用するワークフロー / コンテキストはパック系エンドポイントで扱います。

作成

POST /v1/packs
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "type": "context",
  "title": "Team onboarding",
  "scope": { "type": "personal" },
  "blocks": [
    { "title": "Where things live", "content": "Docs in Notion, code in GitHub, designs in Figma." }
  ]
}

ワークフロー・パックは steps、コンテキスト・パックは blocks を使います。

ワークフローステップの dueDate は、これから実行するワークフローの開始からの相対日数で、"7" のような文字列として保存されます。カレンダー上の日付ではありません。YYYY-MM-DD の期限が必要な場合はタスクの dueDate を使います。

読み取り

GET /v1/packs?reference=@repo-onboarding はデフォルトでアウトラインのデータを返します。すべてのネストした内容が必要なら full=true、一部だけなら blockIds / stepIds を渡します。

パックの参照には UUID、エイリアス、共有 URL、ハブ URL を使えます。

大きなパックではエージェントに渡すコンテキストを小さく保つため、まずアウトラインを読み、必要なネストした内容だけを取得してください。 packs.get は、アウトライン、指定した内容、全文（full=true）のいずれでも同じ 1 credit です。

更新

ネストした内容の更新は操作の配列を使います。

PATCH /v1/packs?reference=@repo-onboarding
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "blocks": [
    { "op": "add", "title": "Local setup", "content": "npm install" },
    { "op": "update", "id": "b001", "content": "Updated" },
    { "op": "remove", "id": "b002" }
  ]
}

steps または blocks を省略するとネストした内容は変更されません。空配列は何もしません。すべて削除する場合は、ネストした項目ごとに remove 操作を送ります。

実行

POST /v1/packs/run はワークフロー・パックをトラックへ展開します。ルート・ゴール 1 件と、ステップごとの todo タスクを 1 回のリクエストで作成します。

POST /v1/packs/run
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "reference": "@release-review",
  "title": "Ship CSV export",
  "startDate": "2026-07-01",
  "assignees": ["human=<user-id>"],
  "context": ["@repo-conventions"],
  "scope": { "type": "projects", "ids": ["<project-id>"] }
}

• ゴールは今回の実行の目的であり、後から実行全体を取得するためのアンカーです。title / content は省略するとパックのタイトルと内容が使われます。
• ステップの相対期日は startDate（省略時は今日）を起点とした絶対日付に変換されます。
• ステップの dependsOn / parentId は作成されたトラックの UUID に解決され、すべてのタスクは goalId でゴールに紐づきます。
• assignees は token=id 形式でパック側の担当トークンをマッピングします。human はユーザー ID へマッピングしてください（エージェント ID はそのまま解決されます）。未マッピングの human ステップは担当なしで作成され、warnings に報告されます。
• context はコンテキスト・パック（ID、エイリアス、URL）を context: ソースとしてゴールに記録します。作成されるすべてのトラックには workflow:<pack-id> ソースが刻まれます。

レスポンスには sourcePackId、goal.id、各タスクの ID と対応する stepId、stepMap、warnings が含まれます。実行全体は後から POST /v1/tracks/search を goalId で絞り込んで取得できます。

パックを評価する

POST /v1/packs/rate は、実際に使ったパックがうまくいったかどうかを評価として記録します。評価はハブに表示される「うまくいった / うまくいかなかった」の件数と、トレンドのランキングに反映されます。

POST /v1/packs/rate
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "reference": "@release-review",
  "outcome": "success"
}

• outcome は success または failure です。
• 実行結果はアカウントとパックの組につき 1 件です。再度呼び出すと前回の結果を更新します（最新優先）。
• パックを実際に使い終えた、または途中で断念したときに評価してください。読んだだけでは評価しません。

検索フィルター

パックの検索は type, query, page, searchMode, scopes と、category, like, visibility, ownerId, minLikeCount, minSuccessCount, updatedAtFrom, updatedAtTo などのフィルターを受け取ります。

searchMode はランキング方式を選びます: keyword（既定）または semantic（キーワード一致にベクトル類似を加味）。省略するとキーワード検索になります。