All documentation
Documentation
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.
sequenceDiagram
participant B as Your backend
participant G as Grade API
participant A as Grade assistant
participant P as The person
B->>G: POST /sdk/v1/agent/token, with the SDK key
G-->>B: Agent token, valid for 15 minutes
B->>A: POST /v2/api/agent, with the token and your model key
A-->>B: The answer as it is written, then a proposal
B->>P: Shows the answer and the confirmation
P->>B: Confirms
B->>G: POST /sdk/v1/agent/commit, with the proposal_token
G-->>B: ReceiptQuickstart
-
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.
-
Mint an agent token
curl -sS "$BASE_URL/sdk/v1/agent/token" \ -X POST \ -H "Content-Type: application/json" \ -H "X-Application-Id: $APP_ID" \ -H "X-Api-Key: $API_KEY" \ -d '{ "end_user": "user_8f3a2c" }'end_useris 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 beforeexpires_at. -
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:curl -sS -N "$AGENT_URL" \ -X POST \ -H "Authorization: Bearer $AGENT_TOKEN" \ -H "x-model: claude-sonnet-5-5" \ -H "x-model-key: $MODEL_KEY" \ -H "Content-Type: application/json" \ -H "Accept: text/event-stream" \ -d '{ "messages": [{ "role": "user", "content": "Which campaigns still need payment terms?" }], "app_events": [], "prior_run_id": null, "formats": ["text", "card"] }'Append each
textevent'sdeltato the answer. Anactionevent is a proposal: show itstextbeside a confirm button, and keep itsproposal_token. On Grade's development environment, also send thecf-access-tokenheader Grade gives you for it. See Ask the assistant. -
Commit what the person confirms
curl -sS "$BASE_URL/sdk/v1/agent/commit" \ -X POST \ -H "Content-Type: application/json" \ -H "X-Application-Id: $APP_ID" \ -H "X-Api-Key: $API_KEY" \ -d '{ "proposal_token": "<the proposal_token from the action event>" }'The answer is a receipt,
saved,partialorrefused, 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.
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
| Read | What it returns | Scope |
|---|---|---|
search_campaigns |
Campaigns the person can see whose name contains every word given, with each one's status, start day, lifetime views and the day they were counted, and how many creators its roster lists (hidden creators aside, as the Campaigns list counts them). | campaigns:read |
search_creators |
Creators of the organization whose name or email contains the words, or with a campaign only the creators on it: "who is on this campaign" is one call, and total_matching counts them all. | campaigns:read |
get_campaign |
One campaign: its status, days, time zone, how many creators (hidden and in a test phase among them), posts and views. | campaigns:read |
list_campaign_dues |
What each campaign owes its creators now, per currency and before the platform fee: the fixed, CPM and bonus amounts pending, the pending manual bonuses (paid apart from the rest), and how many creators a payment now would leave out and why (hidden, in a test phase, awaiting approval, no email). | payouts:read |
list_due_now |
What each campaign owes its creators now, one row per campaign and currency, before the platform fee: the amount due, how many creators it is for, and the day it was calculated. | payouts:read |
explain_creator_payment |
Why one creator in one campaign is or is not paid: what is payable now (fixed, CPM, bonus, manual bonus), what is not and the reason code of each line, when a held line becomes payable, the calculation's state and the reason codes behind it, why the creator would be left out of a payment, and the creator's posts with each one's payment status and reasons. | payouts:read |
search_posts |
Finds the post behind a link the person pasted: its campaign, creator and post ids for explain_creator_payment. | campaigns:read |
search_payouts |
Payouts the person can see (for a Campaign Manager, only those of their campaigns), newest first, filtered by creator, campaign, payout references, phase and sent days. | payouts:read |
list_top_posts |
Posts ranked by a metric, highest first: one campaign's posts, or, with campaign_id empty, every post the organization tracks, in any campaign or none (for a Campaign Manager, the posts on their campaigns only). | analytics:read |
get_creator_terms |
One creator's payment terms and their history, per campaign. | campaigns:read |
list_creators_by_terms |
Creators on the campaigns the person can see, or on one campaign, by their payment terms: "who has no payment terms" is terms "none", and total_matching counts every match. | campaigns:read |
list_campaigns_needing_setup |
The campaigns the person can see whose setup is not done, as each campaign's page asks under "Set up this campaign": creators without payment terms (nothing can be paid until they are set), then creators without posts tracked. | campaigns:read |
list_payment_templates |
The organization's payment terms templates, newest first, as the payment terms editor's Templates list shows them: each one's name, whether it is the default, its terms in the editor's words, and how many creators on the campaigns the person can see are on it. | campaigns:read |
get_approval |
One payout approval request: its campaign, creator, amount, status and who submitted it. | approvals:read |
list_pending_approvals |
Payout requests waiting for an Admin or Finance decision, newest first, as the Approvals page lists them: each one's campaign, creator, the debit approving it takes from the wallet, the day it was requested and how many days it has waited. | approvals:read |
list_approval_history |
Payout requests already decided, newest decision first, as the Approvals page lists them: each one's campaign, creator, the debit approving it took or would have taken from the wallet, its status (approved, denied or cancelled), the day it was requested, and the day it was decided and by whom. | approvals:read |
check_wallet_against_dues |
Whether the organization's wallet covers what is due: the balance, and per currency the amount due, the platform fee the organization pays and the debit in USD at today's rate, then what is needed in all and the shortfall. | payouts:read |
get_payout_period |
Payouts sent between two UTC days, of one campaign or creator or all, grouped by campaign, creator, status or month, with each group's totals per currency and the whole period's totals, which are never cut: "how much did we pay per campaign this quarter" and "monthly spend this year" are one call each, and the totals are the answer, never the rows added up. | payouts:read |
aggregate_performance |
Views, likes, comments and shares of the posts on the campaigns the person can see, with how many posts and creators, grouped by up to two of campaign, creator, platform and day, week or month (at most one of the last three), or not grouped: "views by platform last month", "which creators brought the most views across all campaigns", "weekly views of Summer Launch" and "posts per campaign this quarter" are one call each. total_matching counts every group, and the whole set's totals (in prose) are never cut: they are the answer for any total, never the rows added up (a group's day never goes below zero on its own, so rows may not add up to the totals). | analytics:read |
get_creator_overview |
One creator across the campaigns the person can see, by name or id, in one call: "how is Ana doing", "what do we owe Ana in all" and "what have we paid Ana" read here. | payouts:read |
list_wallet_top_ups |
The organization's wallet top-ups, newest first: when each was made, how it was paid, its status, the top-up amount, the processing fee taken from it, the wallet credit, and when the money is or was available to pay with. | payouts:read |
list_bounced_payout_emails |
Creators whose payout emails did not reach the email address Grade has for them now (the email bounced, failed or was rejected, or they marked it as spam or unsubscribed), most recent first: the creator, how many payout emails did not arrive, and the latest one's payout reference, day and what happened. | payouts:read |
list_payout_disputes |
Payout disputes creators opened, as the Disputes tab of Payouts lists them, open ones first, then the oldest: each one's payout reference, its campaign (none for a Quick Pay payout), the creator, the reason (video_missing, crosspost_not_counted, wrong_amount or other), the status (open, resolved or rejected), whether the creator can still reopen a rejected one, since when the creator has waited for an answer, when Grade reminded the organization and when it escalated the dispute to Grade's team, the day it was opened and the day it was closed. | disputes:read |
list_removed_posts |
One campaign's removed posts, the content taken off it with Remove content, that can still be restored, most recently removed first: each one's creator, platform, the day it went up, the day it was removed, and whether it sat in a cross-post group. | campaigns:read |
list_campaign_posts |
One campaign's live posts, newest first: each one's creator, platform and the day it went up, whether its performance is frozen, and whether it counts toward CPM and bonuses and toward fixed pay (per post and upload goals), or is excluded by its own setting or with its account. | campaigns:read |
list_pay_cycles |
One creator's pay cycles on one campaign whose terms pay in recurring cycles, oldest first: each cycle's dates as the pay breakdown labels them, the amount due in it, and whether it is due, running (the cycle in progress, which can be waived only once it ends), awaiting approval (part of a payout awaiting approval) or waived, with why and when for a waived one. | payouts:read |
list_earnings |
What one creator earned through recorded earnings, and what you agreed with them outside a campaign's payment terms. | payouts:read |
get_earning |
One recorded earning in full: what it is for and what it covers, how it is calculated (the saved explanation and its steps), the evidence behind it (each source, its reference, when it was observed, whether it is complete and its notes; never the files themselves), the agreement version it was recorded under with that version's terms, Grade AI's check of the request (matches, changes or unclear, with its reason, the request and the differences), the amounts earned, paid, in progress and due, its approval and payout, and its history. | payouts:read |
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.
| Action | What it does | Scope | Effect | SDK route |
|---|---|---|---|---|
prepare_trackingTrack links on a campaign |
Proposes account or post links the person gave as tracking for one creator on one campaign. | campaigns:write + campaigns:read |
Adds something that can be undone in Grade. | POST /sdk/v1/campaigns/:id/creators/media |
prepare_tracked_media_addTrack links outside a campaign |
Proposes account or post links the person gave for the organization's Tracking, outside any campaign. | analytics:write |
Adds something that can be undone in Grade. | POST /sdk/v1/analytics/tracked-media/bulk |
prepare_payment_termsSet up payment terms |
Proposes payment terms for one or more creators (up to 20) on one campaign. | campaigns:write + campaigns:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | None |
prepare_campaign_completeComplete a campaign |
Proposes completing one open campaign, which stops its tracking and pending accrual and makes no new payouts from it until it is reopened. | campaigns:write + campaigns:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | POST /sdk/v1/campaigns/:id/complete |
prepare_campaign_reopenReopen a campaign |
Proposes reopening one closed campaign, which resumes its tracking and pending accrual under the creators' existing terms. | campaigns:write + campaigns:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | POST /sdk/v1/campaigns/:id/reopen |
prepare_campaign_updateEdit a campaign |
Proposes changing one campaign's title, description, start date, or its end date when it has one. | campaigns:write + campaigns:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | PATCH /sdk/v1/campaigns/:id |
prepare_campaign_creatorsAdd creators to a campaign |
Proposes creators of the organization to add to one campaign. | campaigns:write + campaigns:read |
Adds something that can be undone in Grade. | POST /sdk/v1/campaigns/:id/creators |
prepare_creator_removalRemove creators from a campaign |
Proposes creators to remove from one campaign. | campaigns:write + campaigns:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | DELETE /sdk/v1/campaigns/:id/creators |
prepare_creator_hideHide a creator on a campaign |
Proposes hiding one creator on one campaign: they stay on it but are left out of payouts due until unhidden. | campaigns:write + campaigns:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | PATCH /sdk/v1/campaign-creators/:id/visibility |
prepare_creator_unhideUnhide a creator on a campaign |
Proposes unhiding one hidden creator on one campaign, which brings them back into the roster and payouts due. | campaigns:write + campaigns:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | PATCH /sdk/v1/campaign-creators/:id/visibility |
prepare_creator_moveMove a creator to another campaign |
Proposes moving one creator from one campaign to another open campaign, with their tracked accounts and posts, payouts, approvals and payment terms. | campaigns:write + campaigns:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | POST /sdk/v1/campaign-creators/:id/move |
prepare_content_removalRemove a post from a campaign |
Proposes removing one post from a creator's content on one campaign. | campaigns:write + campaigns:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | DELETE /sdk/v1/campaigns/:id/creators/media |
prepare_post_restoreRestore a removed post |
Proposes restoring one removed post to its campaign, where it counts toward the creator's pay again. | campaigns:write + campaigns:read |
Adds something that can be undone in Grade. | POST /sdk/v1/campaign-media/:id/restore |
prepare_post_freezeFreeze a post's performance |
Proposes freezing one live post's performance on its campaign, so views it earns from now count toward neither CPM nor bonuses. | campaigns:write + campaigns:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | POST /sdk/v1/campaign-media/:id/freeze-performance |
prepare_post_resumeResume a post's performance |
Proposes resuming one frozen post's performance on its campaign, so views it earns from now count again (those earned while it was frozen stay excluded). | campaigns:write + campaigns:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | POST /sdk/v1/campaign-media/:id/unfreeze-performance |
prepare_post_exclude_performanceExclude a post from CPM and bonuses |
Proposes excluding one live post from CPM and bonuses on its campaign, so its views stop counting toward them. | campaigns:write + campaigns:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | POST /sdk/v1/campaign-media/:id/exclude-performance |
prepare_post_include_performanceInclude a post in CPM and bonuses |
Proposes including one post excluded from CPM and bonuses on its campaign again, so its views count toward them again. | campaigns:write + campaigns:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | POST /sdk/v1/campaign-media/:id/unexclude-performance |
prepare_post_exclude_fixed_rateExclude a post from the fixed rate |
Proposes excluding one live post from fixed pay on its campaign, both per post and upload goals. | campaigns:write + campaigns:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | POST /sdk/v1/campaign-media/:id/exclude-fixed-rate |
prepare_post_include_fixed_rateInclude a post in the fixed rate |
Proposes including one post excluded from fixed pay on its campaign again, both per post and upload goals. | campaigns:write + campaigns:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | POST /sdk/v1/campaign-media/:id/unexclude-fixed-rate |
prepare_pay_bonusSet a creator's pending bonus |
Proposes setting one creator's pending manual bonus on one campaign to the amount the person said, in place of any pending one. | payouts:write + campaigns:read + payouts:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | PUT /sdk/v1/campaign-creators/:id/pending-bonus |
prepare_pay_cycle_waiveWaive a creator's pay cycle |
Proposes waiving one due pay cycle of one creator's recurring terms on one campaign, for the reason the person gave, so it stops being owed. | payouts:write + campaigns:read + payouts:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | POST /sdk/v1/campaign-creators/:id/pay-cycle-windows/waive |
prepare_pay_cycle_restoreRestore a waived pay cycle |
Proposes restoring one waived pay cycle of one creator on one campaign, so it is owed again. | payouts:write + campaigns:read + payouts:read |
Changes or removes something that may not be undoable. Read the confirmation with care. | POST /sdk/v1/campaign-creators/:id/pay-cycle-windows/restore |
Nothing that moves money is offered through the API: Quick Pay and paying payouts stay in Grade.
Models
| Model | x-model |
Provider | Status |
|---|---|---|---|
| Claude Sonnet 5.5 | claude-sonnet-5-5 |
Anthropic | Certified |
| GPT-6.1 Terra | gpt-6.1-terra |
OpenAI | Being certified |
| GPT-5.6 Terra | gpt-5.6-terra |
OpenAI | Reserve, tried if GPT-6.1 Terra does not pass |
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
| Limit | Value |
|---|---|
| Questions per end user | 30 in the last hour and 100 a UTC day |
| Questions per application | 1,000 a UTC day, all end users together |
| Commits per application | 60 a minute |
| Creators or links per proposal | 20 |
| One answer | 2 minutes, 6 model calls, about 150,000 input tokens per call, and an estimated US$0.50 of model use |
| Runs at a time | One per end user |
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.
