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

# REST API

> API keys, scopes and the endpoints your backend calls: attribution, events, creators, benefits, exports, embed tokens and webhooks.

The REST API covers the parts of Rally that connect to your own systems. It is not a second way to run the program; for that, use the app or [an agent over MCP](/mcp/overview).

## Base URL and authentication

```text theme={null}
https://app.runrally.io/v1
```

Create a key under **Settings → API keys**, pick the scopes it needs, and send it as a bearer token:

```bash theme={null}
curl https://app.runrally.io/v1/creators/by-email?email=sam@example.com \
  -H "Authorization: Bearer co_your_api_key"
```

Keys start with `co_` and are shown once. Requests and responses are JSON; amounts are in minor units (cents); times are RFC 3339.

<Note>
  API keys are for the REST API. Agents connecting over MCP use agent keys from **Settings → Agents & MCP**, which carry a role rather than scopes.
</Note>

## Scopes

| Scope | Lets the key |
| - | - |
| `attribution:write` | Report leads and sales, and look up or set a customer's attribution. |
| `events:write` | Send product events (a trial started, a seat added) that reward rules can pay on. |
| `creators:read` | Look up creators and record their accounts in your product. |
| `benefits:write` | See and fulfil non-cash benefits (credits, upgrades) you grant creators. |
| `embed:mint` | Mint short-lived tokens for the [embedded portal](/developers/embed). |
| `exports:read` | Download data exports. |
| `webhooks:manage` | Register and remove [webhook](/developers/webhooks) endpoints. |
| `*` | Everything, including ledger and payout exports. |

## Endpoints

### Attribution

| Method and path | Purpose |
| - | - |
| `POST /v1/track/lead` | A signup: ties your customer id to the referring creator. Send `external_customer_id`, `email`, and either the `ref` and `via` cookies or a `creator_code`. `201` new, `200` already attributed. |
| `POST /v1/track/sale` | Money collected: `external_id` (idempotency key), `external_customer_id`, `amount`, `currency`, `is_subscription`. The response warns when the customer is not attributed. |
| `POST /v1/attribution/customers` | Attribute a customer directly, when you know the creator or referral: `external_customer_id`, plus one of `referral_id`, `creator_code`, `link_code` or `creator_id`. |
| `GET /v1/attribution/customers/{id}` | Who a customer is attributed to, by your customer id. |
| `POST /v1/attribution/resolve` | Which creator a `referral_id` belongs to, without attributing anyone. |

See [Tracking and attribution](/developers/tracking) for where these fit.

### Events

`POST /v1/events` records something a customer did that a reward rule may pay for. Fields: `kind` (`signup`, `activation`, `install`, `connect`, `action`, `lead` or `custom`) and `name` (your own event name), who it was (`external_customer_id`, or `creator_email` / `creator_code` for things a creator did), `occurred_at`, a free-form `payload`, and a `dedupe_key` so retries are safe. `201` new, `200` seen before.

### Creators

| Method and path | Purpose |
| - | - |
| `GET /v1/creators/by-email?email=` | A creator by email: id, status, programs, code. |
| `GET /v1/creators/{id}` | A creator by id. |
| `POST /v1/creators/{id}/product-accounts` | Record the creator's account in your product (`provider`, `external_id`, `workspace_name`) so Rally can show it and grant benefits to it. |

### Benefits

| Method and path | Purpose |
| - | - |
| `GET /v1/benefits?unfulfilled=true` | Benefits Rally granted that your product still has to apply (free months, credits, an upgrade). |
| `POST /v1/benefits/{id}/fulfil` | Mark one applied, with a `ref` to your side and any `usage` detail. |

### Exports

`GET /v1/exports/{kind}` returns a zip of CSV files. Kinds: `creators`, `candidates`, `applications`, `briefs`, `resources`, `content`, `analytics`, `attribution`, `ledger`, `payouts`, `audit`, `full`. The `ledger`, `payouts` and `full` kinds need the `*` scope.

### Embed tokens

`POST /v1/embed/tokens` mints a token that signs one creator into one portal module inside your app. See [Embed the creator portal](/developers/embed).

### Webhooks

`GET`, `POST` and `DELETE /v1/webhooks`, plus `GET /v1/webhooks/events` for the event names. The same can be done under **Settings → Webhooks**. See [Webhooks](/developers/webhooks).

## Errors

Errors are JSON with an `error` message and a `code`. `401` is a missing or revoked key, `403` a scope the key does not have, `404` an id not in your workspace, `409` a state conflict, `429` too many requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.