Documentation / SDK v1

Grade SDK API

External API reference for Grade SDK endpoints.

grade sdk api · json
{
  "success": false,
  "message": "This API key is missing the required scope: payouts:write"
}
All documentation

Base path

Most SDK endpoints are under:

/sdk/v1

The compact campaign creator list is versioned separately at:

GET /sdk/v2/campaigns/:campaignId/creators

Authentication (required on every request)

Send these headers on every request:

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

If the application has an origin allowlist configured:

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

Every API key carries a set of scopes, chosen when the key is created and editable afterwards from the developer portal. A scope is written <domain>:<action>, where the action is read or write.

Domain Covers
analytics Tracked media, collections, and performance metrics.
campaigns Campaigns, campaign creators, contracts, campaign media, crosspost groups, and bonus templates.
payouts Wallet balance, transactions, invoices, payout history, and sending payouts.
approvals Read payout approval requests and approve, reject, or cancel them.
disputes Read payout disputes and their proof, reply to them, and resolve or reject them.
kyc Recipient onboarding and identity verification.

write does not imply read, so a domain has four possible states and the portal offers all of them: No access, Read only, Write only, and Read and write. A key that should both list and mutate a domain needs both scopes.

A call whose key is missing the required scope answers 403 and names what is missing:

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

Two notes worth knowing before you design around this:

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

Keys that existed before scopes shipped were granted every scope, so nothing changed for them. Newly introduced domains such as approvals and disputes must be granted explicitly. Rotating a key preserves its scopes.

Idempotency (required on payout, crosspost, and dispute writes)

These endpoints require X-Idempotency-Key:

  • 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
  • POST /sdk/v1/disputes/:id/reply
  • POST /sdk/v1/disputes/:id/resolve

Idempotency keys are scoped per application and operation. Re-using the same key returns the previously stored response.

Dispute keys are scoped per dispute and return the dispute as it is now. See Payout disputes.

Reading Quick Pay approval status or GET /sdk/v1/payouts/approvals/:approvalId (approval requests created by Payouts when approval mode is on) requires payouts:read but does not require X-Idempotency-Key.

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

Campaign management

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"

Platform workflows

Describe your program.

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