Skip to main content
Beta. The assistant API and its reads over MCP are in beta. They are open to every organization that pays out through Grade, and parts are not available yet, as each page says.
Each question is one POST to the assistant’s URL, which ends in /v2/api/agent. Grade keeps no conversation for you: every request carries the history and the open proposals again.

Headers

Request body

JSON, at most 32 KB in UTF-8. A field this page does not name is refused with 400. History is text only. An assistant message holds an answer’s text deltas, joined. Proposals never go in messages: they go back as app events.

App events

Both kinds carry "type": "app_event" and the time in at.
  • open_proposal goes with every question for the latest proposal of each action, until a newer one arrives, so the person can correct it in words (“add Maya too”). It carries the proposal’s action_id and action, its status (open, or applied once a row saved) and the draft the action event gave. Only a proposal with a draft, which comes with the card format, has one.
  • action goes once, with what became of a proposal:
The optional counts holds whole numbers: added for saved rows, failed for refused and not_sent, and unconfirmed for unknown, leaving out zeros.

Events

The answer is text/event-stream: each frame is an event: line and a data: line with one JSON object. A frame starting with : (: keep-alive, every 15 seconds while the model thinks) is a comment: skip it. The x-agent-run-id response header carries the run’s id, on refusals too: log it and quote it when you contact Grade. run_started comes first and turn_completed last, with any number of step_started, step, text and action between them. A stream that closes without turn_completed, or sends error instead, failed: treat it as stream_error.
The answer’s text is a small Markdown subset (paragraphs, headings, lists, small tables, bold and inline code) with no links or images. Draw it with a renderer that escapes HTML, or as plain text: it is model-written, and it quotes data from people outside your team.

A proposal

An action event without a proposal_token has nothing to commit: show no confirm button. When a newer proposal of the same action arrives, turn the older one’s button off. When a proposal can’t be sent, no action event comes: its step ends with PROPOSAL_TOO_LONG or PROPOSAL_UNAVAILABLE, and the assistant says so in words.

Every event and its fields

run_started

step_started

step

text

view_delta

view

view_rejected

action

turn_completed

error

Refusals before the stream

A refused question answers JSON, { "code": "..." }, and no stream.

How an answer ended

turn_completed.run_outcome says how an accepted question ended, and error_class why, in one word. Try again resends the same request.

Compatibility

Events and fields are only ever added: ignore an event or a field you don’t know, and read a new run_outcome or error_class as a failure. A change you would have to adapt to comes as a new api_version, which you ask for. The request is the other way round: Grade refuses what it doesn’t know.