API overview

The Rekomi API is JSON-over-HTTPS. Every request needs an API key. Every response is JSON. Every error follows the same shape.

Base URLs

• Production: https://api.rekomi.com/api/v1
• Staging: https://api-staging.rekomi.com/api/v1

Content type

All requests and responses use application/json. UTF-8 encoded. No XML, no form-encoded bodies.

Content-Type: application/json
Accept: application/json

Authentication

Every endpoint (except a small set of public ones like /api/p/by-handle/{handle}/{campaign}, /api/p/by-domain, and /api/v1/track/click) requires a bearer token in the Authorization header:

Authorization: Bearer rk_live_xxxxxxxxxxxxxxxxxxxxx

Generate API keys at /dashboard/settings/api-keys. See Authentication for the full lifecycle (create, rotate, revoke, scope to read vs write).

S2S tracking and webhook payloads have a separate HMAC signing step on top of the bearer auth. See S2S tracking and Webhooks.

Errors

Business-rule errors under /api/v1 are JSON in this shape; endpoints outside /api/v1 return compatible JSON errors but are not guaranteed to carry all three keys:

{
  "error": "plan_tier_required",
  "message": "White-label embed requires Growth tier or higher."
}

• error: a stable string code. Use this for branching logic in your code. Codes never change once published.
• message: a human-readable description. Subject to change. Do not parse.
• field (optional): the field that triggered the error, when relevant.

Not every failure uses this envelope. Request-validation failures (a malformed body or query parameter) return a standard problem details object with an errors map ({ type, title, status, errors }), 401 responses carry no body, and many 404s are body-less too.

Common error codes:

Never parse the message field. Always branch on error.

Rate limits

Limits are partitioned per user for authenticated calls (API-key calls share the bucket of the user who created the key), and per IP for anonymous and webhook traffic:

When you exceed the limit, the response is HTTP 429 with an empty body. Wait, then retry with exponential backoff for sustained spikes.

Pagination

The core resource lists (programs, affiliates, conversions, payouts) return cursor-based pagination envelopes; a few auxiliary lists (pending applications, fraud events, leaderboards) return flat arrays instead:

GET /api/v1/conversions?take=100&cursor=eyJpZCI6MTIzNH0

• take: page size. Max 200, default 50. (One exception: GET /api/v1/conversions returns 100 rows when take is omitted.)
• cursor: opaque cursor returned in a prior response's nextCursor field. Omit for the first page.

Response shape:

{
  "items": [ /* up to `take` items */ ],
  "nextCursor": "eyJpZCI6MTIzNH0",
  "hasMore": true
}

When hasMore is false, you have reached the end.

Idempotency

For write endpoints that create new resources, you can supply an Idempotency-Key header (UUID v4 recommended). Within a 60-minute window, the same key with the same payload returns the prior response. The same key with a different payload returns HTTP 409.

Idempotency-Key: 8f14e45f-ceea-467a-bb2c-d8b8c0afc8d8

Use this for any write you might retry on network failures.

CORS

The API has restrictive CORS. The default allowlist covers Rekomi's own surfaces (rekomi.com, app.rekomi.com), every branded {handle}.rekomi.com subdomain, and each brand's verified custom portal domain. For server-to-server calls (Node.js, Go, Python, anything not in a browser), CORS doesn't apply, so make whatever request you like.

For browser-side requests from your own domain, proxy through your application server. We don't add arbitrary partner origins beyond the Rekomi surfaces, branded subdomains, and verified custom portal domains above.

The white-label embed iframe is a separate flow with its own per-token origin allowlist; see Embed.

Plan requirements

Programmatic access (API keys) is gated by plan tier. The in-app dashboard at app.rekomi.com is unrestricted on every paid tier; only rk_live_* API calls are gated. The hosted MCP server is the exception: it works on every plan including Trial, since each tool call is relayed through mcp.rekomi.com and gated per-tool by your AI client's consent loop rather than by a direct-API plan check.

Trial users get the features of the tier they picked at signup for the trial window; a Starter trial does not unlock Growth or Pro features. Plan gates fire as 402 plan_tier_required with the required + current tier in the body:

{
  "error": "plan_tier_required",
  "required": "Growth",
  "current": "Starter",
  "trialing": false,
  "message": "White-label embed requires Growth tier or higher. Upgrade in Settings → Billing."
}

The dashboard (app.rekomi.com) authenticates via Clerk JWTs and bypasses plan gates so brand operators can always see and manage their own data regardless of tier.

Versioning

All routes live under /api/v1. We will introduce /api/v2 if and when we make breaking changes. v1 stays available for at least 24 months after v2 ships. Deprecations are announced via the blog and a Deprecation header on responses.

Machine-readable docs

LLMs and coding agents integrating against Rekomi should fetch /llms/api.txt, a single-file manifest enumerating every /api/v1/* endpoint, request and response shape, error codes, plan gates, webhook events, signature verification steps, and rate-limit policies in plain prose with structured headings. The manifest is updated alongside API releases and is the canonical machine-consumable spec; this page and the rest of /docs/developers/* are the human-friendly views of the same surface.

Where to go next

• Authentication: generate keys, manage scopes.
• S2S tracking: server-side conversion ingest.
• Track leads and signups: capture free signups (automatic for Stripe and Paddle) and email-match a later sale.
• Webhooks: receive events from Rekomi.
• Embed: host an affiliate's dashboard on your domain.
• MCP: connect Claude, Cursor, or ChatGPT to your account via the hosted MCP server.
• Reference: every v1 endpoint with method, scope, and example.