Packs

Use pack endpoints for reusable workflows and context.

Create

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." }
  ]
}

Workflow packs use steps; context packs use blocks.

Workflow step dueDate is a relative number of days from a future workflow run, stored as a string such as "7". It is not a calendar date. Use task dueDate for YYYY-MM-DD deadlines.

Read

GET /v1/packs?reference=@repo-onboarding returns outline data by default. Add full=true for all nested content, or pass blockIds / stepIds for selected content.

Pack references can be UUIDs, aliases, share URLs, or hub URLs.

For large packs, read the outline first to keep agent context small, then fetch only the nested content needed. packs.get costs the same 1 credit for outline, selected-content, and full-content (full=true) reads.

Update

Nested content updates use operation arrays.

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" }
  ]
}

Omitting steps or blocks keeps nested content unchanged. Passing an empty array is a no-op. Use one remove operation per nested item to delete all items.

Run

POST /v1/packs/run expands a workflow pack into a track: one root goal plus one todo task per step, created in a single request.

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>"] }
}

• The goal is the run's objective and retrieval anchor. title/content default to the pack's when omitted.
• Relative step due dates become absolute dates counted from startDate (default: today).
• Step dependsOn/parentId ids are resolved to the created track UUIDs; every task links to the goal via goalId.
• assignees maps pack assignee tokens as token=id pairs. Map human to a user id; agent ids resolve as-is. Unmapped human steps are left unassigned and reported in warnings.
• context records context packs (by id, alias, or URL) as context: sources on the goal. Every created track carries a workflow:<pack-id> source.

The response includes sourcePackId, goal.id, each task's id with its source stepId, a stepMap, and warnings. Fetch the whole run later with POST /v1/tracks/search filtered by goalId.

Rate a pack

POST /v1/packs/rate rates the outcome of using a pack. Rated outcomes feed the success/failure counts shown on the hub and the trending ranking.

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

• outcome is success or failure.
• One outcome per account and pack: repeating the call updates the previous outcome (latest wins).
• Rate after finishing or abandoning actual use of the pack, not after merely reading it.

Search filters

Pack search supports type, query, page, searchMode, scopes, and filters such as category, like, visibility, ownerId, minLikeCount, minSuccessCount, updatedAtFrom, and updatedAtTo.

searchMode selects the ranking mode: keyword (default) or semantic (keyword matching plus vector similarity). Omit it for keyword search.