> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.usegrade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ask the assistant

> The request, the events of the answer, and every refusal and ending.

**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

| Header | Value |
| - | - |
| `Authorization` | `Bearer <agent token>`, from [Mint an agent token](https://api-docs.usegrade.com/agent/token.md). |
| `x-model` | The id of a model Grade serves, such as `claude-sonnet-5-5`. See [Models](https://api-docs.usegrade.com/agent/overview.md#models). |
| `x-model-key` | Your API key for that model's provider. Used for this turn only, never stored. |
| `x-model-workspace` | Optional, Claude only: your Anthropic workspace id (`wrkspc_…`), which a key not scoped to a workspace needs. |
| `Content-Type` | `application/json` |
| `Accept` | `text/event-stream` |
| `cf-access-token` | Only on Grade's development environment: the header Grade gives you for it. |

## Request body

JSON, at most 32 KB in UTF-8. A field this page does not name is refused with `400`.

| Field | Type | Required | Meaning |
| - | - | - | - |
| `messages` | array | Yes | The conversation, oldest first: 1–400 messages of `{ "role": "user" \| "assistant", "content": string }`. The last one is the person's question: `user`, not blank, at most 2,000 characters. |
| `app_events` | array | Yes | What became of proposals, at most 32 events (below). Send `[]` when there is none. |
| `prior_run_id` | string or `null` | Yes | The `run_id` of the previous answer in this conversation; `null` for the first question. |
| `formats` | array | No | The proposal formats you want: `text`, `card` or `composition`, 1–3 entries. Omitted, you get every format your organization has on. Composition is off in the beta. |
| `conversation_id` | string | No | A UUID you choose per conversation, so Grade's records group its answers. |
| `history_trimmed` | boolean | No | `true` when you left the oldest messages out to stay within the limits. |

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.

```json theme={null}
{
  "messages": [
    { "role": "user", "content": "Which campaigns still need payment terms?" },
    { "role": "assistant", "content": "Two campaigns have creators without payment terms: ..." },
    { "role": "user", "content": "Add Maya Chen and Leo Park to Summer Launch." }
  ],
  "app_events": [],
  "prior_run_id": "7d0c5c8e-2f61-4b8e-9a51-3c1f0f7a9e24",
  "formats": ["text", "card"]
}
```

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

```json theme={null}
{
  "type": "app_event",
  "kind": "action",
  "at": "2026-10-28T18:03:40.000Z",
  "action_id": "act_4f9c1b",
  "action": "prepare_campaign_creators",
  "outcome": "saved"
}
```

| Commit result | `outcome` |
| - | - |
| Receipt `saved` | `saved` |
| Receipt `partial` with a `saved` row | `saved`, with `counts` |
| Receipt `partial` without one | `unconfirmed` |
| Receipt `refused`, or a refused commit | `rejected` |
| `504`, or no answer: it may have been written | `unconfirmed` |
| The person dismissed it | `closed` |

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

```text theme={null}
event: run_started
data: {"run_id":"9b2e7f4a-1c3d-4e5f-8a6b-7c8d9e0f1a2b","context_version":"3f9a1c2e","api_version":1}

event: step_started
data: {"tool":"list_campaigns_needing_setup"}

event: step
data: {"tool":"list_campaigns_needing_setup","status":"ok","ms":412}

event: text
data: {"delta":"Two campaigns have creators without payment terms: "}

event: turn_completed
data: {"run_outcome":"answered","error_class":null,"usage":{"input":18234,"output":412,"cache_read":0,"cache_write":0},"cost_usd":0.061,"model":"claude-sonnet-5-5"}
```

| Event | What to do |
| - | - |
| `run_started` | Keep `run_id`: it is the next request's `prior_run_id`. |
| `step_started` | A read or an action started; `tool` names it. You may show that the assistant is working. |
| `step` | It ended: `status` is `ok` or `error`, with a `code` on error. Its other fields are diagnostics. |
| `text` | Append `delta` to the answer. |
| `action` | A proposal, below. |
| `turn_completed` | The end. `run_outcome` says how it ended (below), with `usage`, `model` and `cost_usd`, an estimate: your provider bills the real cost. |
| `error` | Grade could not finish the answer; `code` names why. |
| `view_delta`, `view`, `view_rejected` | Only with composition, which is off in the beta. |

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

```json theme={null}
{
  "action_id": "act_4f9c1b",
  "action": "prepare_campaign_creators",
  "text": "Add creators · Summer Launch\nTo add:\nMaya Chen: New on this campaign\nLeo Park: New on this campaign",
  "proposal_token": "eyJhbGciOiJFZERTQSIsInR5cCI6ImFnZW50LXByb3Bvc2FsK2p3cyIs...",
  "payload": { "...": "the card's data" },
  "draft": { "campaign_id": "CAMP_123", "creator_ids": ["CR_1", "CR_2"] },
  "args": null
}
```

| Field | Meaning |
| - | - |
| `action_id`, `action` | The proposal's id and the action's name, from [Actions](https://api-docs.usegrade.com/agent/overview.md#actions). |
| `text` | The confirmation, at most 4,000 characters, written by Grade's code, never the model. Show it as plain text beside the confirm button. |
| `proposal_token` | The signed proposal. Send it to [the commit](https://api-docs.usegrade.com/agent/commit.md) unchanged. It is signed, not encrypted, and holds your organization's data: keep it on your backend. |
| `payload` | The proposal's data, to draw your own card, or to ignore. |
| `draft` | Only with `card`: send it back in `open_proposal`. |
| `args` | For Grade's evaluations. Ignore it. |

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`

| Field | Type | Sent |
| - | - | - |
| `run_id` | string (a UUID) | Always |
| `context_version` | string (matching `^[a-f0-9]{8,64}$`) | Always |
| `api_version` | `1` | When it applies |

#### `step_started`

| Field | Type | Sent |
| - | - | - |
| `tool` | string (matching `^[a-z][a-z0-9_]{0,63}$`) | Always |

#### `step`

| Field | Type | Sent |
| - | - | - |
| `tool` | string (matching `^[a-z][a-z0-9_]{0,63}$`) | Always |
| `status` | one of `ok`, `error` | Always |
| `ms` | number (at least 0) | Always |
| `code` | string (matching `^[\w.:-]{1,80}$`) or `null` | When it applies |
| `method` | `"GET"` or `null` | When it applies |
| `route` | string (at most 256 characters) or `null` | When it applies |
| `rows` | number (an integer, at least 0) or `null` | When it applies |
| `args` | object or `null` | When it applies |
| `output_keys` | array of string (at most 80 characters) or `null` | When it applies |
| `detail` | object: `args`, `rows`, `truncated` | When it applies |

#### `text`

| Field | Type | Sent |
| - | - | - |
| `delta` | string | Always |

#### `view_delta`

| Field | Type | Sent |
| - | - | - |
| `view_id` | string (matching `^[\w-]{1,128}$`) | Always |
| `seq` | number (an integer, at least 0) | Always |
| `text` | string | Always |

#### `view`

| Field | Type | Sent |
| - | - | - |
| `view_id` | string (matching `^[\w-]{1,128}$`) | Always |
| `program` | string | Always |
| `statements` | number (an integer, at least 0) | Always |
| `fallback` | boolean | When it applies |

#### `view_rejected`

| Field | Type | Sent |
| - | - | - |
| `view_id` | string (matching `^[\w-]{1,128}$`) | Always |
| `rule_ids` | array (at most 100 items) of string (matching `^[\w.:-]{1,80}$`) | Always |
| `next` | one of `repair`, `none` | Always |
| `detail` | object: `lines` | When it applies |

#### `action`

| Field | Type | Sent |
| - | - | - |
| `action_id` | string (matching `^[\w-]{1,128}$`) | Always |
| `action` | string (matching `^[a-z][a-z0-9_]{0,63}$`) | Always |
| `payload` | object | Always |
| `args` | object or `null` | When it applies |
| `draft` | object | When it applies |
| `text` | string (at most 4,000 characters) | When it applies |
| `proposal_token` | string (at most 65,536 characters, matching `^[\w-]+\.[\w-]+\.[\w-]+$`) | When it applies |

#### `turn_completed`

| Field | Type | Sent |
| - | - | - |
| `run_outcome` | one of `answered`, `refused_access`, `session_expired`, `tool_failed`, `model_error`, `stream_error`, `max_tokens`, `refusal`, `step_cap`, `paused`, `budget_exhausted`, `client_aborted`, `worker_exception` | Always |
| `error_class` | string (matching `^[\w.:-]{1,80}$`) or `null` | When it applies |
| `usage` | object: `input`, `output`, `cache_read`, `cache_write` | When it applies |
| `cost_usd` | number (at least 0) or `null` | When it applies |
| `model` | string (matching `^[a-z0-9.-]{1,64}$`) or `null` | When it applies |
| `resets_at` | string (an ISO 8601 timestamp) or `null` | When it applies |

#### `error`

| Field | Type | Sent |
| - | - | - |
| `code` | string (matching `^[\w.:-]{1,80}$`) | Always |

## Refusals before the stream

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

| Status | `code` | Meaning |
| - | - | - |
| `400` | `invalid_request` | The body does not match this page. |
| `400` | `MODEL_KEY_MISSING` | Send your provider key in `x-model-key`. |
| `400` | `MODEL_NOT_ALLOWED` | `x-model` names no model this environment serves; the body's `models` lists the ones it does. |
| `400` | `MODEL_WORKSPACE_INVALID` | `x-model-workspace` is not an Anthropic workspace id, or the model is not Claude. |
| `401` | `AGENT_TOKEN_MISSING`, `AGENT_TOKEN_INVALID` | Mint a new token and send the same request once more. |
| `403` | `refused_access` | The key's scopes reach no read and no action, or the assistant is not open to your organization. |
| `403` | `FORMATS_UNAVAILABLE` | Neither `text` nor `card` is left once your organization's formats meet the request's. |
| `409` | `run_in_progress` | This end user already has an answer running. Wait for `turn_completed`. |
| `503` | `AGENT_UNCONFIGURED` | Not configured on Grade's side. Contact Grade if it lasts. |

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

| `run_outcome` | `error_class` | Meaning | Try again |
| - | - | - | - |
| `answered` | | The answer is complete. | |
| `client_aborted` | | You stopped it. | |
| `refused_access` | `access_revoked` | The assistant or your application's access was switched off since the token was minted. | No |
| `session_expired` | | The token ran out. Mint a new one first. | Yes |
| `paused` | none, `budget_unbound` | The assistant is paused. | No |
| `paused` | `access_unavailable`, `budget_unavailable` | Busy for a moment. | Yes |
| `budget_exhausted` | `end_user_hour`, `end_user_day`, `app_day` | A [limit](https://api-docs.usegrade.com/agent/overview.md#limits) was reached; `resets_at` says when it opens again. | No |
| `model_error` | `key_rejected` | Your provider refused the model key, or an Anthropic key needs `x-model-workspace`. | No |
| `model_error` | `spend_limit` | Your provider account reached its spending limit or quota. | No |
| `model_error` | `overloaded`, `rate_limited`, `api_error`, `timeout` | Your provider is busy. | Yes |
| `model_error` | `invalid_request` | Your provider refused the request. Start a new conversation if it happens again. | No |
| `tool_failed` | the read's code | Grade couldn't load the data. | Yes |
| `step_cap` | `context_cap`, `run_cost_cap`, other | The question needs more than one answer can do. Ask a narrower one. | No |
| `max_tokens` | | The answer was cut short. | No |
| `refusal` | | The assistant can't help with that. | No |
| `stream_error`, `worker_exception` | | Something went wrong. | Yes |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.