# query

> **Preview.** This page describes the interface WIRK launches with. The hosted service is in private staging and access is by invitation. What is live today: /docs/index.md#what-is-live-today

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

| You send | Mode | Default depth |
|---|---|---|
| `fetch` | Fetch items by ID, short ID, exact title, or `ID@N` for revision N | `full` |
| `about` | Find what matters for these words, ranked by meaning | `card` |
| `fields` only | List with filters, newest change first | `card` |
| `receipt` | The stored receipt of a write, review or upload | |
| nothing | The newest changes | `card` |

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

## Request

```
POST /v2/query
Authorization: Bearer <token>

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

| Key | Notes |
|---|---|
| `fetch` | 1–32 refs: an ID, a short ID, an exact title, or `{"ref": "5c1e7a90", "revision": 2}` |
| `about` | 1–500 characters |
| `fields` | Filters, below |
| `receipt` | A `request_id` |
| `depth` | `card`, `full` or `all` |
| `sort` | `changed` (default), `title` or a field key; a leading `-` reverses |
| `limit` | 1–100, default 20; lists and `about` only |
| `max_bytes` | 1,024–65,536 |
| `cursor` | Continue the identical request |
| `workspace_id`, `format` | As everywhere |

## 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.

| Command | Body sent |
|---|---|
| `wirk query` | `{}` |
| `wirk query 6a0d2e83` | `{"fetch": ["6a0d2e83"]}` |
| `wirk query 'Weekly sync' 5c1e7a90@2` | `{"fetch": ["Weekly sync", {"ref": "5c1e7a90", "revision": 2}]}` |
| `wirk query about='hook drain' status=open` | `{"about": "hook drain", "fields": {"status": "open"}}` |
| `wirk query status=open,in_progress kind=work owner=me limit=50` | `{"fields": {"status": ["open", "in_progress"], "kind": "work", "owner": "me"}, "limit": 50}` |
| `wirk query kind=context state=active` | `{"fields": {"kind": "context", "state": "active"}}`: active initiatives |
| `wirk query proposal=proposed,deferred` | `{"fields": {"proposal": ["proposed", "deferred"]}}`: proposals waiting for a decision |
| `wirk query text='a, b'` | `{"fields": {"text": "a, b"}}` |
| `wirk query linked=2f9b3c4e depth=card` | `{"fields": {"linked": "2f9b3c4e"}, "depth": "card"}` |
| `wirk query receipt=w-3f9a2c41d0` | `{"receipt": "w-3f9a2c41d0"}` |

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:

| Key | Values |
|---|---|
| `kind` | `work`, `context`, `folder`, `doc` |
| `state` | An initiative's state: `active`, `paused`, `done` |
| `proposal` | Lists proposals in these states: `proposed`, `deferred`, `accepted`, `rejected` |
| `status` | The wirkspace's status options, for example `open`, `in_progress`, `completed`, `cancelled` |
| `owner` | `me`, `none`, or a principal |
| `linked` | An item ID: items linked to it, either way |
| `folder` | A folder ID, or `root` |
| `changed_days` | 1–3650 |
| `text` | Exact words in the title or body |
| `archived` | `false` (default) or `true` |

Proposals are not items, so `kind` never lists them; use `proposal=`. Fields your wirkspace defines (`priority`, `delivery_phase`, …) work like `status`. [status](/docs/status.md) 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"`):

```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](/docs/errors.md).