Grade SDK API

​

Base path

​

Authentication (required on every request)

• X-Application-Id: Your SDK application ID.
• X-Api-Key: Your SDK API key secret.

• If the request includes an Origin header, it must match the allowlist.
• If the request omits Origin (common server-to-server), allowlist checks are skipped.

​

Scopes (what a key is allowed to do)

{
  "success": false,
  "message": "This API key is missing the required scope: payouts:write"
}

• The HTTP method is not the rule. Several endpoints are POST but are pure reads, and they require :read, not :write. That includes POST /payouts/status, POST /payouts/pending, POST /payouts/pending-bulk, POST /wallet/check-payout-balance[-bulk], and the two POST /campaign-creators/.../query endpoints. So a read-only key can still check a balance before a payout is approved elsewhere.
• Reference endpoints need no scope. GET /timezones and GET /settings answer for any valid key.

​

Idempotency (required on payout and crosspost writes)

• POST /sdk/v1/payouts/trigger
• POST /sdk/v1/payouts/trigger-bulk
• POST /sdk/v1/payouts/confirm
• POST /sdk/v1/payouts/confirm-bulk
• POST /sdk/v1/payouts/cancel
• POST /sdk/v1/campaign-creators/payouts/bulk
• POST /sdk/v1/campaign-creators/:campaignCreatorRecordId/quick-pay
• POST /sdk/v1/campaign-creators/:campaignCreatorRecordId/crosspost-groups
• PATCH /sdk/v1/campaign-creators/:campaignCreatorRecordId/crosspost-groups/memberships
• POST /sdk/v1/campaign-creators/:campaignCreatorRecordId/crosspost-groups/recompute

​

Limits and validation

• Supported payout currencies: USD, CAD, GBP, EUR
• Currency precision: money amounts must be positive and have max 2 decimals
• Payout batches: up to 100 items per request
• Campaign creator v1 reads: up to 100 creators per page
• Campaign creator v2 reads: up to 500 creators per page or request
• Eligibility score batches: up to 500 media items per request
• Pending payout TTL: 7 days
• Exports: require from and to and are capped at 10,000 rows

​

Response conventions

• Most JSON endpoints return { success: boolean, ... }.
• Balance check endpoints return { sufficient: boolean } (no success wrapper).
• Export endpoints and invoice PDFs return file content (text/csv or application/pdf).

​

Pages

• MCP server — connect an MCP-compatible AI client to your Grade account
• Payouts
• Campaign quick pay — custom one-off payments attributed to a campaign
• Bonus templates
• Wallet
• Transactions
• Creators
• KYC
• Invoices
• Settings
• Timezones — list accepted IANA names and display-friendly labels
• Standalone analytics — track accounts and posts outside campaigns, manage collections, and query performance

​

Campaign management

• Campaigns — create, list, update, delete campaigns and manage campaign creators
• Campaign creators (v2) — use the compact response for new integrations
• Campaign creators (v1 legacy) — preserve the original response for existing clients
• Campaign creator visibility — hide or unhide a creator within a campaign
• Move a creator — move a creator and their history between campaigns in your agency
• Payout report data — read the rows and totals behind a creator’s payout report as JSON
• Campaign contracts — manage creator contracts and payment terms (optional)
• Campaign media — track media, manage creator content, and read performance metrics
• Media eligibility — read and update eligibility scores for tracked posts

​

Minimal example (curl)

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"