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.
The assistant API puts the assistant your team uses in Grade inside your own product. It reads your organization’s data, answers in words, and prepares changes as proposals. Nothing is written until a person confirms a proposal and your backend commits it. Your backend holds every key and talks to Grade. Your interface talks only to your backend.

Quickstart

1

Give your SDK key the Assistant access

In Grade, open Developer, then your application, and edit its key. Full access includes the assistant. With Custom, set Assistant to read and keep read access to the areas you want answers about. Existing keys don’t get it on their own.
2

Mint an agent token

end_user is your own id for the person asking: 1–128 letters, digits, _ or -, never an email. The token lasts 15 minutes. Keep one per person and reuse it until shortly before expires_at.
3

Ask the assistant

The assistant’s URL is https://app.usegrade.com/v2/api/agent. Send your model’s id and your key for its provider:
Append each text event’s delta to the answer. An action event is a proposal: show its text beside a confirm button, and keep its proposal_token. On Grade’s development environment, also send the cf-access-token header Grade gives you for it. See Ask the assistant.
4

Commit what the person confirms

The answer is a receipt, saved, partial or refused, with one row per creator or post. Only this call writes, after a person confirms: a “yes” typed in the conversation never commits. Read Commit a proposal before you retry one.
Keep the SDK key, the agent token and the model key on your backend: never in a browser, a mobile app or a log. An agent token reads your organization’s data within its scopes until it expires.

What it can do

A key needs agent:read, shown as Assistant, to mint a token and to commit. Its other scopes decide what the assistant offers. A read needs the read scope of the routes it calls. An action needs its write scope and the read scopes of what it reads first, since write does not imply read. A key whose scopes reach no read and no action is refused with 403 refused_access. Scopes are copied into the token, so a change applies from the next one.

Reads

Actions

Each action is offered when the key holds every scope listed (its write scope and the read scopes of what it reads first) and the action is on for your organization. Its commit calls the SDK v1 route listed, with your key. An action with no route is offered in words only: its confirmation comes with nothing to commit. Nothing that moves money is offered through the API: Quick Pay and paying payouts stay in Grade.

Models

Production serves only certified models: Grade runs its evaluation suite through the assistant with a model before it certifies it. During the beta, Grade’s development environment also serves the OpenAI models as candidates. Your model key is used for its turn only and never stored, and your provider bills every question to your account.

Limits

A question over a limit gets a stream that ends at once with budget_exhausted and says when the limit opens again. A second question while one runs is refused with 409, and a commit over the limit with 429.