Reference

REST API

Everything the MCP server does is also available over plain HTTP, so n8n workflows, cron jobs, and custom code get the same surface. Base URL below; all routes are under /v1.

Authentication

Create an API key in the dashboard at https://app.affiliateos.dev/developers and pass it as a Bearer token. Keys look like aff_live_..., are shown once, and are stored only as SHA-256 hashes.

shell

curl https://api.affiliateos.dev/v1/accounts \
  -H "Authorization: Bearer aff_live_..."

Keys carry scopes; the defaults are read and links:create. Key management itself (create, list, revoke) requires a dashboard session, so a leaked API key can’t mint more keys.

Conventions

Topic	Behavior
Rate limit	120 requests per minute per key. Exceeding it returns 429 with a `Retry-After` header.
Errors	Every error is `{ error: { code, message } }` with a matching HTTP status.
Pagination	List endpoints take `?cursor=&limit=` (default 25, max 100) and return a cursor for the next page.
Content type	JSON in, JSON out.

Networks & accounts

GET /v1/networks

Supported networks with their credential field specs and help text.

GET /v1/accounts

Your connected accounts with status and last sync.

POST /v1/accounts

Body { network, label, credentials }. Credentials are verified against the network before being sealed and stored; invalid ones are rejected with the connector’s reason.

DELETE /v1/accounts/:id

POST /v1/accounts/:id/sync

Force a sync, rate-limited to once per five minutes per account.

Programs

GET /v1/programs

Hybrid search. Query params: query, network, vertical, status, min_commission_pct. Uses semantic search when an embeddings key is configured and falls back to keyword matching otherwise.

GET /v1/programs/:id

Full detail including commission summary and cookie window.

Tags & links

GET /v1/tags

POST /v1/tags

Body { tag, description?, metadata? }. Idempotent; posting an existing tag returns it.

POST /v1/links

Body { destination_url, attribution_tag, program_id?, account_id? }. Requires the links:create scope. Resolves the monetizing program by domain when program_id is omitted and returns MONETIZATION_NOT_FOUND when nothing covers the URL.

shell

curl -X POST https://api.affiliateos.dev/v1/links \
  -H "Authorization: Bearer aff_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destination_url": "https://runfastgear.example/peak-x2",
    "attribution_tag": "newsletter-2026-07"
  }'

POST /v1/links/bulk

Up to 50 URLs under one tag, with per-URL results.

GET /v1/links

Your links, filterable by attribution_tag.

Transactions, earnings & payments

GET /v1/transactions

Query params: from, to, status, network, attribution_tag, program_id. Defaults to the last 30 days.

GET /v1/earnings/summary

Query params: from, to, group_by=network|program|tag|day, currency=USD. Amounts are converted with daily exchange rates and split by status: pending, approved, reversed, paid.

GET /v1/payments

Payout records, filterable by date range.

Events & webhooks

GET /v1/events

Pull-based event feed. Query params: after (an event id or ISO timestamp high-water mark) and types.

POST /v1/webhooks

Body { url, event_types[] }. Returns the signing secret once. See the webhooks page for verification.

GET /v1/webhooks

DELETE /v1/webhooks/:id

API keys

GET /v1/keys

POST /v1/keys

DELETE /v1/keys/:id

These three routes only accept a dashboard session (Supabase JWT), never an API key. That’s deliberate: a leaked key must not be able to create more keys.