Reference

briefing.today

today: the first call of every session: what changed since your last briefing (ranked by severity), releases by version with scope left and ready-to-ship-early, who holds which ticket, what waits on Yan, can_take (tickets at your level). Pass since (the cursor of an earlier reply) to see only newer changes

Needs issues:read · REST GET /api/v1/briefing

issue.list

list: issues as compact rows (key, title, status, assignee, release), filtered by app, state_group or status, release or type, paged by cursor (limit up to 100, pass next_cursor back until it is gone); fields adds named fields; since returns only issues changed after an earlier reply's cursor (and removed: archived since)

Needs issues:read · REST GET /api/v1/issues, GET /api/v1/tasks

issue.get

get: one issue with its state, release, done means and lock

Needs issues:read · REST GET /api/v1/issues/{ref}

issue.create

create: a new issue in an app (lands in Triage unless state_group says otherwise); call issue.fields first: the type's template fills description and done_means, and required custom fields must be sent in custom

Needs issues:write · REST POST /api/v1/issues

issue.update

update: title, description, priority, change_risk (or risk_tier), done_means, custom (field values by key), type, severity, source, reporter, external_url, affected_version, platform, device, repro_steps, review_steps, blocked, blocked_reason, snooze_until, must_have, size, first/last_seen_at, occurrence_count, waiting_on_yan and release_note (null clears), no_code with reason. Needs the ticket's lock, except a patch of only description and/or done_means, which needs no lock and never changes the state

Needs issues:write · REST PATCH /api/v1/issues/{ref}

issue.fields

fields: the custom fields (kind, choices, required, help) and templates for an app and issue type, so create and update fill them correctly

Needs issues:read · REST GET /api/v1/issues/fields

issue.move

move: to a status column (state_group) and/or a release; started plus reason on a ticket in review sends it back (needs comments:write); review and Done need a run receipt and a PR or branch link (or no_code with a reason), frozen releases and high-risk work need Yan's approval; the reply gives `state` and `held`, and a held move names the approval it waits on

Needs issues:write · REST POST /api/v1/issues/{ref}/move

issue.comments

comments: list an issue's comments, oldest first; since returns only comments after an earlier reply's cursor

Needs comments:read · REST GET /api/v1/issues/{ref}/comments

issue.comment

comment: add a comment to an issue

Needs comments:write · REST POST /api/v1/issues/{ref}/comments, POST /api/v1/tasks/{ref}/progress

issue.ci_result

ci_result: record a CI run (commit, result pass|fail, flakes, log path); Done needs a pass on the merged commit

Needs comments:write · REST only, not in MCP · REST POST /api/v1/issues/{ref}/ci

issue.receipt

receipt: submit the run receipt (files_changed, risks, verified [{what, how}], decisions, next_step, done_means [{item, met, evidence}], head_sha of the commit it covers); needed before review and for the Mishka approval merge check

Needs issues:write · MCP only

issue.review

review: record your pass or fail on one commit of someone else's ticket (head_sha is the full commit; you cannot review a ticket you filed a receipt on); a pass on the commit being merged lets Yan's high-risk rule decide without a click

Needs issues:write · MCP only

issue.receipts

receipts: the run receipts on an issue, newest first

Needs issues:read · MCP only

issue.scan

scan: record a scanner's findings for a commit: tool, head_sha (the commit), findings [{severity high|medium|low, path, line, rule, link}], [] if none. VOLAT runs no scanner. An open high finding blocks approving that commit

Needs issues:write · MCP only

issue.restore

restore: take a ticket out of the archive (canceled goes to Backlog)

Needs issues:write · REST POST /api/v1/issues/{ref}/restore

issue.archive_closed

archive_closed: owner only; archive all due closed tickets (state_group limits it)

Needs issues:write · MCP only

issue.archive

archive: soft-delete a ticket you hold; more than one ticket becomes an approval for Yan

Needs issues:write · destructive · MCP only

issue.code_status

code_status: report branch/PR state on a ticket you hold (repo, branch, pr_number, pr_url, preview_url, pr_state, check_state, mergeable); omit to read

Needs issues:read · MCP only

issue.relations

relations: what this issue blocks, is blocked by, duplicates or relates to

Needs issues:read · REST GET /api/v1/issues/{ref}/relations

issue.relate

relate: link to another issue (kind blocks, blocked_by, duplicate_of, related_to); duplicate_of also moves this one to Canceled

Needs issues:write · REST POST /api/v1/issues/{ref}/relations

issue.unrelate

unrelate: remove a relation by its id (from issue.relations)

Needs issues:write · REST DELETE /api/v1/issues/{ref}/relations/{id}

issue.seen

seen: intake saw this issue again (a matching crash or review): bumps occurrence_count and last_seen_at instead of filing a duplicate

Needs issues:write · REST POST /api/v1/issues/{ref}/seen

issue.attachments

attachments: list an issue's screenshots and logs (metadata)

Needs issues:read · REST GET /api/v1/issues/{ref}/attachments

issue.attach

attach: add a screenshot or log to a ticket you hold (file_name, content_type image/png|image/jpeg|image/gif|image/webp|text/plain|text/csv|application/json|application/pdf|application/zip|application/x-ndjson, content_base64; 10 MB at most)

Needs issues:write · REST POST /api/v1/issues/{ref}/attachments

issue.start

start: one call to begin a ticket: takes the lock (checkout.take), starts a session (pass machine and branch) and returns the context pack (context.ticket) with any handoff note

Needs issues:write · REST POST /api/v1/issues/{ref}/start, POST /api/v1/tasks/{ref}/claim

issue.finish

finish: one call to hand a ticket over: files the run receipt (the receipt fields), adds comment, reports the link (repo, branch, pr_url) or no_code: true with a reason, moves it (state_group review by default; completed closes it in this one call when every done_means item is answered met with evidence) and ends your session. The reply gives `state` and `held`; a held finish names the approval it waits on. One refusal lists everything missing; extra done_means items on a ticket with none are kept as notes

Needs issues:write · REST POST /api/v1/issues/{ref}/finish, POST /api/v1/tasks/{ref}/finish

issue.mirror_export

mirror_export: an app's tickets as Markdown files (tasks/KID.md or backlog/tasks/*.md) with stable ids; you write them into the repo

Needs issues:read · REST only, not in MCP · REST GET /api/v1/mirror

issue.mirror_sync

mirror_sync: send the edited mirror files back; preview by default, apply: true writes status ticks, title edits and new tasks in one changeset (Undo), and refuses on conflicts

Needs issues:write · REST only, not in MCP · REST POST /api/v1/mirror

checkout.take

take: lock a ticket before working on it (one ticket, one agent); returns the previous holder's handoff note

Needs issues:write · MCP only

checkout.ping

ping: keep your locks alive during long builds or test runs (for coding-tool hooks); any other call also renews them

Needs issues:read · REST POST /api/v1/checkout/ping

checkout.release

release: let go of a ticket with a handoff note (what was done, next step, open questions)

Needs issues:write · destructive · MCP only

checkout.pause

pause: stop with a note and release the lock; reason limit_hit (tool reported its plan used up) also offers the ticket to another tool

Needs issues:write · destructive · MCP only

checkout.resume

resume: take a paused or handed-off ticket and get the note it was left with

Needs issues:write · MCP only

checkout.mine

mine: the tickets you hold and when each lock expires

Needs issues:read · MCP only

No arguments.

checkout.available

available: tickets offered to another tool (limit hit) and locks that went stale

Needs issues:read · MCP only

No arguments.

context.ticket

ticket: everything for one ticket: description, done means, release, linked docs, guidelines, related tickets, comments, receipts, sessions, approvals

Needs issues:read · MCP only

context.app

app: one app's resume card: why it exists, state, last change, next step, open risks; revive/park/archive if stale

Needs issues:read · REST GET /api/v1/apps/{ref}/resume

guidelines.list

list: the rules every agent follows: first the switches (id "switches", from Settings > Agent rules), then the written rules (workspace-wide, plus the app's own when app is given); read before starting work. Reading them acknowledges the current rules_version

Needs docs:read · REST GET /api/v1/guidelines

guidelines.get

get: one guideline by id

Needs docs:read · MCP only

guidelines.export

export: rules as AGENTS.md text for any agent (default), or format claude (CLAUDE.md), both, or skill (a Claude Code SKILL.md); you write the files in your PR

Needs docs:read · REST GET /api/v1/guidelines/export

guidelines.put

put: add or update a guideline (needs docs:admin)

Needs docs:admin · MCP only

session.start

start: begin a session on a ticket you hold; returns the last pause note on that ticket if there is one

Needs sessions:write · MCP only

session.log

log: record a step (kind plan, action, question, result, error); a question waits for Yan's answer

Needs sessions:write · MCP only

session.link

link: attach the branch and pull request to the session

Needs sessions:write · MCP only

session.pause

pause: stop with a handoff note and release the ticket; reason limit_hit offers it to another tool

Needs sessions:write · destructive · MCP only

session.resume

resume: pick up a paused session (yours or another tool's) from its note; takes the ticket and starts a new session

Needs sessions:write · MCP only

session.finish

finish: end the session as done or error, with a summary and the branch/PR

Needs sessions:write · MCP only

session.get

get: one session with all its steps

Needs sessions:read · MCP only

session.list

list: sessions, by issue, status or only yours

Needs sessions:read · MCP only

session.waiting

waiting: sessions waiting for Yan's answer (Needs-you)

Needs sessions:read · MCP only

No arguments.

release.list

list: open releases per app, oldest version first, with open/done counts, checklist counts and ready_to_ship

Needs releases:read · REST GET /api/v1/releases

release.get

get: one release by uuid, or by version with app

Needs releases:read · REST GET /api/v1/releases/{ref}

release.readiness

readiness: a release's pre-release checklist (full item ids; who: agent or person for each, so you know before ticking), open must-haves, and what still blocks shipping

Needs releases:read · REST GET /api/v1/releases/{ref}/readiness

release.tick

tick: tick (done true, the default) or untick a checklist item by its id from readiness, with an optional note as evidence ("build 412 from 3f9c2e1"). On a person-only item (who: person) the note is saved for Yan, who ticks from it; shipping is Yan's alone

Needs releases:write · REST POST /api/v1/release-checks/{id}

release.update

update: internal_only true marks a release as an internal build (tracked, never shipped or announced as public, never ships next), false clears it (people only)

Needs releases:write · MCP only

release.close_tickets

close_tickets: close several tickets to Done in one call (issues: keys, reason: the comment on each), each under issue.finish's gate; the reply says per key what closed and what was refused and why

Needs issues:write · MCP only

approval.request

request: ask Yan before merge_pr, deploy_production, send_external_message, publish_release_notes, rotate_or_create_key, change_agent_permissions; returns a pending approval (moves into frozen releases, high-risk moves and bulk archives become approvals on their own)

Needs approvals:write · REST POST /api/v1/approvals

approval.get

get: one approval, its status and agent_hint (what to do now; a send-back note is in it). An expired approval is refused with approval_expired

Needs approvals:read · REST GET /api/v1/approvals/{id}

approval.list

list: approvals, by status, issue or only yours

Needs approvals:read · REST GET /api/v1/approvals

approval.resubmit

resubmit: after Yan asks for a revision, send it back with a note saying what changed

Needs approvals:write · REST POST /api/v1/approvals/{id}/resubmit

idea.search

search: find ideas by words, app, type, status or linked work

Needs ideas:read · MCP only

idea.get

get: one idea with its research, comments and links

Needs ideas:read · MCP only

idea.create

create: capture an idea (title is enough); items[] captures several

Needs ideas:write · MCP only

idea.update

update: edit title, description, app or type; send the revision you read

Needs ideas:write · MCP only

idea.research_add

research_add: add a research entry (a finding, never an edit to the idea)

Needs ideas:write · MCP only

idea.research_edit

research_edit: change a research entry you wrote

Needs ideas:write · MCP only

idea.comment

comment: add a comment under a research entry

Needs ideas:write · MCP only

idea.link

link: link an idea to tickets, an app or related ideas; items[] links several

Needs ideas:write · MCP only

idea.unlink

unlink: take a link off an idea

Needs ideas:write · MCP only

idea.similar

similar: find ideas that may say the same thing

Needs ideas:read · MCP only

undo.list

list: your own recent changes that can still be undone (VOLAT data only)

Needs issues:read · REST GET /api/v1/undo

undo.apply

apply: undo one of your own changes by changeset_id; refused if later work touched the same fields or it would re-enter a frozen release

Needs issues:write · destructive · REST POST /api/v1/undo

usage.report

report: spend for this run: input_tokens/output_tokens and/or plan_usage_pct with plan_window (5h, weekly, monthly); idempotency_key makes retries safe

Needs usage:write · MCP only

usage.limits

limits: this key's scopes, rate limit, writes left today, open flags, today's spend and every agent's plan headroom

Needs usage:read · MCP only

No arguments.

usage.metrics

metrics: push readings per app (mrr, users, crashes, app_store_status), up to 100 at once; a repeated app + metric + as_of is stored once, so retries are safe

Needs metrics:write · REST only, not in MCP · REST POST /api/v1/metrics

docs.list

list: docs as titles and excerpts, newest first; filter by kind (doc, decision, guideline), app, issue or q (text match). kind=guideline lists the agent rules; kind=decision is the decisions log

Needs docs:read · REST GET /api/v1/docs

docs.get

get: one doc with its full markdown text, app, linked ticket, decision status and version (the text version; pass it back as if_version). section gives that section's text only

Needs docs:read · REST GET /api/v1/docs/{id}

docs.versions

versions: the doc's text versions, newest first (at most 50), with when and who

Needs docs:read · MCP only

docs.version

version: the doc's full text as it was at a version (from docs.versions)

Needs docs:read · MCP only

docs.put

put: add a doc (no id) or change one (id; only the fields you pass). Link it to an app or a ticket (a ticket implies its app). Decisions take decision_status and decided_on. Agent rules (kind guideline) need docs:admin

Needs docs:write · REST POST /api/v1/docs, PATCH /api/v1/docs/{id}

docs.section_put

section_put: replace one section (its heading line through the line before the next heading) with content, heading included. Saved when that section is unchanged since if_version, even if others edited the rest; refused (conflict) otherwise

Needs docs:write · MCP only

docs.archive

archive: move a doc to the trash (a person can restore it from Settings › Trash)

Needs docs:write · destructive · REST DELETE /api/v1/docs/{id}

help.get

get: how a session goes, a tool's actions, or one action's arguments (topic: issue or issue.finish)

Needs any valid key · REST GET /api/v1/help

help.connect

connect: what a new agent is told on connect: how VOLAT works, this key's rules, the REST routes (REST only)

Needs any valid key · REST only, not in MCP · REST GET /api/v1/connect

No arguments.

search.query

query: ranked matches for q (words, "a phrase", or, -not; a ticket key like KID-4 comes first) across tickets, comments, docs, decisions, agent rules, ideas, agent sessions, run receipts, releases and apps; narrow with kinds, app and filters. One row per record, best first, up to 200 results: pass next_cursor back (same arguments) for the next page; changed_since_first_page means the workspace changed since page 1. complete is true only when the results ended on this page, nothing was cut at 200 and not_searched is empty; when it is false and you need every match, use search.list

Needs issues:read · REST GET /api/v1/search

search.list

list: every match page by page, newest first by created (default), updated or completed; q is optional (without it, everything the filters allow); same filters as query; pass next_cursor back (same arguments) until it is gone; sort=created is the full walk; under sort=updated a record edited mid-walk can be missed and the reply says so (changed_since_first_page, complete false); complete is true only on the last page when not_searched is empty

Needs issues:read · REST GET /api/v1/search/list

search.changes

changes: what changed since a cursor, across tickets, comments, docs, ideas, sessions and receipts; since is the cursor from an earlier reply (without it the reply is only the cursor); events: created, updated (other fields), content_changed (title or text), moved (status), archived (restorable), restored, deleted (gone for good); more = ask again

Needs issues:read · REST GET /api/v1/search/changes

search.activity

activity: what happened in the workspace, newest first, one line per burst; filter by actor (name), app, kind (tickets, releases, docs, approvals), from/to (YYYY-MM-DD) and q; older with before = next_cursor

Needs issues:read · REST GET /api/v1/activity

feedback.push

push: store App Store reviews, in-app feedback or emails per app, up to 100 at once; a repeated app + source + source_id is stored once, so retries are safe

Needs feedback:write · REST only, not in MCP · REST POST /api/v1/feedback

feedback.list

list: feedback newest first, by app, status, source or reply state (reply=approved lists replies a person approved and you may post now)

Needs feedback:read · REST only, not in MCP · REST GET /api/v1/feedback

feedback.reply

reply: attach a drafted reply; it becomes a send_external_message approval and nothing is sent until a person approves, then you post it and call posted

Needs feedback:write · REST only, not in MCP · REST POST /api/v1/feedback/{id}/reply

feedback.posted

posted: you posted the approved reply yourself (VOLAT never posts); refused unless a person approved that exact text

Needs feedback:write · REST only, not in MCP · REST POST /api/v1/feedback/{id}/posted