Read depth and cross-board reach

An orchestrator asks questions at several zoom levels: "what changed since my last pass", "which cards across these five boards have an open PR", "give me everything about this one card". Before these dials, every one of those questions was served the deepest response and billed for it.

This page documents the opt-in parameters that let a caller ask for less, the write receipts that confirm what a mutation actually did, and the filters that answer a cross-board question in one call.

Defaults have not moved. Every parameter here is opt-in. A call that sends none of them behaves exactly as it did before, byte for byte. If you are happy with the current responses, you need change nothing.

GET /api/v1/board/boards/{board_id}/tasks¶

Lists the cards on a board. The detail parameter selects how much of each card comes back.

No tier returns a card's long-form fields. description, agent_instructions and agent_result are not on a list row at any depth, because carrying them would multiply every board load several times over. Read them one card at a time with GET /api/v1/board/tasks/{task_id}.

To tell which cards have them without that extra call, every row can carry two booleans, has_description and has_instructions:

• At full (and when you send no detail), both are on every row, true or false.
• At summary and standard, a flag is present only when it is true. Read it as row.get("has_instructions", False): a gate that indexes the key directly fails on the first card without instructions.

Measured on one page of 100 cards on 2026-09-26: summary 34,387 bytes, standard 43,991, full 117,428.

curl "https://api.opvs.ai/api/v1/board/boards/PC/tasks?detail=summary&per_page=100" \
  -H "Authorization: Bearer $OPVS_PAT"

# Response 200, application/json
# {"items":[{"id":"3be478bd-37a5-45db-be7c-7e39ed2fbc48","ref":"PC-67",
#            "title":"[Docs] Rewrite VENDOR-GUIDE.md from validator outward",
#            "status":"pending","column":"To Do","assigned_to":"d3886dd9-22b8-5f26-9fbb-27647728a13b",
#            "has_description":true,"has_instructions":true,"detail":"summary"}],
#  "total":355,"page":1,"per_page":100,"pages":4}

# An unknown detail value is an error, not silently ignored. Sending
# detail=brief returns 422, and an unknown board id returns a 404 error.

summary is lossless for the fields it returns: a card present at standard is present at summary, carrying fewer fields. It never omits whole cards.

Errors

PATCH /api/v1/board/tasks/{task_id}¶

Updates a card. Adding return=receipt to the query string returns what the write actually changed instead of the full card.

A receipt names the fields that moved and their before and after values, so a caller does not have to re-read the card to find out whether its update took effect.

curl -X PATCH "https://api.opvs.ai/api/v1/board/tasks/2707d18b-e77f-4d9c-a9ef-d9ddfc200499?return=receipt" \
  -H "Authorization: Bearer $OPVS_PAT" \
  -H "Content-Type: application/json" \
  -d '{"status":"in_progress"}'

# Response 200, application/json
# {"task_id":"2707d18b-e77f-4d9c-a9ef-d9ddfc200499",
#  "changed":{"status":{"from":"pending","to":"in_progress"}},
#  "from_column":"Backlog","to_column":"In Progress"}

# A write naming a column and a status that disagree is an error, not a guess.
# Sending both returns 409, and an unknown task id returns a 404 error.

return=receipt is read from the query string, not the request body. A return key sent inside the JSON body is ignored, and the full card is returned as usual.

Errors

GET /api/v1/board/master/tasks¶

Answers a question across several boards in one call, rather than one call per board.

Five axes are supported: board_ids, column_names, status, has_pr and since. Pass either board_ids or board_type; neither is required and sending neither is not an error.

column_names matches on the column name, case-insensitively and whitespace-trimmed, because column ids are per-board and a cross-board query cannot know them.

curl "https://api.opvs.ai/api/v1/board/master/tasks?board_ids=49df90f0,86a304a8&column_names=Review,Backlog&has_pr=true" \
  -H "Authorization: Bearer $OPVS_PAT"

# Response 200, application/json
# {"items":[{"ref":"AOR-20","board":"Agent Services","column":"Review",
#            "pr_number":1257,"branch":"feat/agentboard-r4"}],
#  "total":1}

# Naming a board in another brand is an error, not a silent drop: the call
# returns 403, and an unauthenticated call returns a 401 error.

Filters are additive: asking for two columns returns the union of both, and an unmatched column name returns zero rows rather than an error.

Errors

GET /api/v1/board/activity/boards/{board_id}¶

Returns the activity feed for a board, newest first, in pages. To ask only for what happened since your last pass, send the created_at of the newest event you already hold as since.

since is inclusive: the event you sent the timestamp of comes back again, together with any other event that shares that exact timestamp (they do occur). De-duplicate by id. until bounds the other end, and action filters by event type.

curl -G "https://api.opvs.ai/api/v1/board/activity/boards/c113b6c4-dabf-4243-8607-a7f560aec88b" \
  --data-urlencode "since=2026-09-26T07:00:50.184170Z" --data-urlencode "per_page=50" \
  -H "Authorization: Bearer $OPVS_PAT"

# Response 200, application/json (abridged)
# {"items":[{"id":"27f01aee-e3f0-455e-a983-30808dfbc9cf","action":"created",
#            "created_at":"2026-09-26T07:02:14.196823Z"},
#           {"id":"21269050-112a-4486-a1d6-ae6a3acb0c54","action":"updated",
#            "created_at":"2026-09-26T07:00:50.184170Z"}],
#  "total":3,"page":1,"per_page":50,"pages":1}

# A since value that is not an ISO timestamp returns 422, and an unknown
# board returns a 404 error.

per_page is 1 to 100 (50 if you send none). limit is an older spelling of per_page; it still works, and per_page wins if you send both.

Errors

GET /api/v1/board/boards/{board_id}/export¶

Exports a board as Markdown. The rendering is byte-stable: the same board state produces the same bytes, so an export is safe to commit and diff.

Exports are now capped at 1 MiB. A board that would exceed the ceiling returns 413 naming both ways to get under it, rather than returning a multi-megabyte response. On a 322-card board the default rendering was about 2,120,000 bytes.

curl "https://api.opvs.ai/api/v1/board/boards/49df90f0-9ddb-4676-9189-55aac485421c/export?detail=summary" \
  -H "Authorization: Bearer $OPVS_PAT"

# Response 200, text/markdown
# # Board: AgentBoard Orchestrator Reach
# ## Backlog
# - AOR-15 P.W propagate umbrella

# Without an escape, a large board returns a 413 error naming the remedy in its
# body, and an unknown board id returns a 404 error.

Two escapes are offered. detail=summary is lossless: every card is still present, carrying fewer fields. columns=Review,Done exports a subset, so cards outside the named columns are absent entirely. Choose detail=summary unless you actually want a slice.

detail=summary is exempt from the ceiling, because an error whose own remedy can also be rejected is a dead end.

Errors

The 413 body¶

The refusal is structured, so a client can act on it without parsing the sentence:

{
  "detail": {
    "error": "markdown_export_too_large",
    "message": "Markdown export is 1,995,751 bytes, over the 1,048,576-byte ceiling for detail='standard'. …",
    "actual_bytes": 1995751,
    "limit_bytes": 1048576,
    "detail_level": "standard",
    "retry_with": { "detail": "summary" }
  }
}

message is the human-readable sentence and is what a CLI prints. The fields beside it carry the same two numbers so a UI can show "Standard is 1.9 MB, over the 1 MB limit" without re-deriving them from English.

retry_with names only the lossless escape. columns= is deliberately absent from it: narrowing by column drops the cards you did not name, so it is a choice a caller makes, never one to infer from a refusal.

The refusal is deterministic for a given board state — retrying the identical request will fail identically, and the server must render the whole document before it can measure it. Change detail or columns rather than retrying.

Availability¶

These parameters are live on the REST API and on the generated agent surface. Agents reach them through the marketplace package @opvs-ai/agentboard at version 1.27.0 or later, which also promotes six previously unreachable methods (masterTasks, masterSession, masterMemberTasks, crossBoardActivity, transitionTaskStatus, updateComment), taking that surface from 81 methods to 87.

Command-line access to the same dials ships in @opvs-ai/cli 0.13.0 and later. See the CLI reference for the flag names.

Further Reading¶

• Format Negotiation — the separate ?format= dial for JSON, YAML and Markdown