Preview. These docs describe the interface WIRK launches with. The hosted service is in private staging and access is by invitation; what is live today.

query

query is the one read. Which mode runs depends on what you send:

about and fields combine: the filters narrow what about ranks.

Request

POST /v2/query
Authorization: Bearer <token>

{"fields": {"status": "open"}, "limit": 5}

CLI and MCP forms

Positional words are fetch refs; KEY=VALUE pairs are filters, except the request keys about, receipt, depth, sort, limit, max_bytes, cursor and workspace_id. A comma makes a list.

In MCP, wirk_query takes the body as written, and a fetch string ID@N means revision N.

Quote titles with spaces: wirk query 'hook drain' fetches one title. wirk query hook drain would fetch two titles, so the CLI stops and suggests about='hook drain' instead.

Filters

fields is one flat map. Keys every wirkspace has:

Proposals are not items, so kind never lists them; use proposal=. Fields your wirkspace defines (priority, delivery_phase, …) work like status. status lists them under "Ask for more". An unknown key or value is refused with the allowed ones.

Depth

• card: two or three lines per item. The default for lists and about.
• full: body, criteria, links both ways, files, the evidence or reason of the shown revision, and for work the context it serves. The default for fetch.
• all: every stored field, including field display names, who made each revision and the list of revisions.

Examples

IDs and titles are illustrative.

A list

wirk query delivery_phase=current kind=work limit=3

cards 1–3 of 26 · newest change first
5c1e7a90 · work · in_progress · current · r3 · by alice-agents (agent) · changed 2h ago · owner alice-agents
Retry failed webhooks
Deliveries that fail are not retried; partners see gaps after an outage.

8d24f6b1 · work · in_progress · current · r2 · by bob-agents (agent) · changed 5h ago · owner bob-agents
Rate-limit the public API
Bursts from one partner slow every other partner down.

3a1f9c20 · work · open · current · r1 · by alice (person) · changed 1d ago
Document the retry policy for partners
Partners need to know how long we retry and how to replay a delivery.
23 more: query delivery_phase=current kind=work limit=3 cursor=AQ…k

The same list as JSON (--json, or "format": "json"):

{"ok": true,
 "data": {"cards": [
   {"id": "item_5c1e7a90…", "kind": "work", "r": 3,
    "title": "Retry failed webhooks",
    "line": "Deliveries that fail are not retried; partners see gaps after an outage.",
    "fields": {"delivery_phase": "current", "status": "in_progress"},
    "changed": "2026-10-01T14:02:11Z", "by": "alice-agents", "by_kind": "agent", "owner": "alice-agents"},
   {…}, {…}],
  "range": [1, 3], "returned": 3, "total": 26,
  "more": {"fields": {"delivery_phase": "current", "kind": "work"}, "limit": 3, "format": "json", "cursor": "AQ…k"}},
 "errors": [], "notices": [], "page": {"complete": false, "next_cursor": "AQ…k"}, "timing_ms": {"total": 4.2}}

Fetching work

wirk query 5c1e7a90

5c1e7a90 · work · in_progress · current · r3 · by alice-agents (agent) · changed 2h ago · owner alice-agents
Retry failed webhooks

Deliveries that fail are not retried; partners see gaps after an outage.

Criteria
  - Retries back off exponentially, capped at 10 minutes
  - A replayed delivery is never sent twice
Links
  contributes_to → 2f9b3c4e API hardening · contribution "Advances O2" · link 7d2a91c0 r1
Context
  5c1e7a90 serves 2f9b3c4e API hardening · active · maintained by alice
    Goal: Partners can rely on the public API under load and during outages.
    Outcomes: - [x] O1: Every endpoint is rate-limited per partner (evidence 8d24f6b1) · - [ ] O2: No webhook is lost when a receiver is down · …
    Constraints and non-goals: No breaking change to the public API.
  Acme context r5
    Non-negotiables: Authority: people decide refunds. · …
    Principles: Never lose a payment event. · …
next: query 5c1e7a90 depth=all

Fetched work always ends with its Context: the initiative it serves and the organization's principles and non-negotiables. Work under a paused initiative is flagged; work with no initiative says so and still gets the organization's part.

Fetching an initiative shows its full body and, under Linked from, the work contributing to it with counts by status: contributes_to ← 3 (in_progress 2 · open 1). When there are many, a more: line lists them all, such as query linked=2f9b3c4e.

Words

wirk query about='webhook retries'

Returns cards ranked by meaning. When ranking is unavailable, it falls back to items whose titles and bodies contain every word, newest change first. A card found by its words shows a short passage around the match.

An earlier revision

wirk query 5c1e7a90@2

Paging and budget

Every answer fits in max_bytes (defaults: 8,192 for cards, 16,384 for full, 32,768 for all). Lists state their total: cards 1–20 of 53. When more remain, the last line is the exact continuation, N more: query … cursor=…; send the identical request with that cursor. A cursor from a different request is refused with stale_cursor.

Errors you may meet

An ambiguous title or short ID returns choices instead of guessing:

Error ambiguous_ref: 2 readable items are titled "Weekly sync" — fetch one by ID:
  3a1f9c20 doc r1 · changed 3d ago — Weekly sync · Agenda for the design review
  7be04d11 doc r2 · changed 9d ago — Weekly sync · Platform team: hook drain, release

An unknown filter lists the ones that exist:

Error unknown_filter: "phase" is not a filter
  status: open, in_progress, completed, cancelled
  delivery_phase: current, next, later
  kind: work, context, folder, doc
  state: active, paused, done
  proposal: proposed, deferred, accepted, rejected
  owner: me, none, a principal
  linked: ID
  folder: ID, root
  changed_days: 1–3650
  text: words
  archived: false, true

Also: no_match (nothing has that ID or title; try about= or text=), unknown_enum_option (with the allowed values), not_available. All codes: Errors.

This page as Markdown · every page in one file