Documentation / Grade AI

Ask the assistantBeta

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

ask the assistant · json
{
  "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"]
}
All documentation

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.
x-model The id of a model Grade serves, such as claude-sonnet-5-5. See 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.

{
  "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:
{
  "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.

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

{
  "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.
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 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 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.

Describe your program.

Grade turns it into a program it can track and pay.