REST API

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.

Base URL and authentication

https://app.runrally.io/v1

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

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.

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.

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.
`exports:read`	Download data exports.
`webhooks:manage`	Register and remove webhook 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 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.

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.

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.

Get started

Agents & MCP

Developers

Base URL and authentication

Scopes

Endpoints

Attribution

Events

Creators

Benefits

Exports

Embed tokens

Webhooks

Errors

​Base URL and authentication

​Scopes

​Endpoints

​Attribution

​Events

​Creators

​Benefits

​Exports

​Embed tokens

​Webhooks

​Errors

Base URL and authentication

Scopes

Endpoints

Attribution

Events

Creators

Benefits

Exports

Embed tokens

Webhooks

Errors