Documentation / Grade AI

Assistant APIBeta

Put the Grade assistant in your own product, with four calls from your backend.

wallet balance · bash
BASE_URL="https://<your-backend-host>"
APP_ID="app_..."
API_KEY="sk_..."

curl -sS "$BASE_URL/sdk/v1/wallet/balance" \
  -H "X-Application-Id: $APP_ID" \
  -H "X-Api-Key: $API_KEY"
All 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.

Sequence, as Mermaid source
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: Receipt

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

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

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

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

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_tracking
Track 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_add
Track 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_terms
Set 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_complete
Complete 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_reopen
Reopen 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_update
Edit 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_creators
Add 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_removal
Remove 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_hide
Hide 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_unhide
Unhide 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_move
Move 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_removal
Remove 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_restore
Restore 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_freeze
Freeze 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_resume
Resume 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_performance
Exclude 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_performance
Include 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_rate
Exclude 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_rate
Include 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_bonus
Set 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_waive
Waive 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_restore
Restore 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.

Describe your program.

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