> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.usegrade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grade SDK API

> External API reference for Grade SDK endpoints.

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

## Idempotency (required on payout 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`

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

## 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](/mcp) — connect an MCP-compatible AI client to your Grade account
* [Payouts](/payouts)
* [Bonus templates](/bonus-templates)
* [Wallet](/wallet)
* [Transactions](/transactions)
* [Creators](/creators)
* [KYC](/kyc)
* [Invoices](/invoices)
* [Settings](/settings)
* [Timezones](/timezones) — list accepted IANA names and display-friendly labels
* [Standalone analytics](/analytics) — track accounts and posts outside campaigns, manage collections, and query performance

### Campaign management

* [Campaigns](/campaigns) — create, list, update, delete campaigns and manage campaign creators
* [Campaign creators (v2)](/campaign-creators/list) — use the compact response for new integrations
* [Campaign creators (v1 legacy)](/campaign-creators/list-v1) — preserve the original response for existing clients
* [Campaign contracts](/campaign-contracts) — manage creator contracts and payment terms (optional)
* [Campaign media](/campaign-media) — track media, manage creator content, and read performance metrics
* [Media eligibility](/campaign-media/eligibility-scores) — read and update eligibility scores for tracked posts

## Minimal example (curl)

```bash theme={null}
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"
```