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