REST API v1

Related: Integrations hub · Developer hub · Webhooks · MCP

Requirements

• Paid plan
• API key with read scope (reads) or write scope (mutations; also satisfies read)
• Authorization: Bearer rf_live_… on every request

New keys default to read,hooks,mcp,wp — add write when generating or editing a key for contest mutations.

Base URL

https://app.rewardsfuel.com/api/v1

OpenAPI specification

Machine-readable contract generated from the same Zod schemas as the API runtime. Use for codegen, Make custom apps, and conformance checks.

https://app.rewardsfuel.com/api/v1/openapi.json

Interactive explorer (Swagger UI): https://app.rewardsfuel.com/api/v1/docs

Response envelope

{ "ok": true, "data": { ... }, "error": null }
{ "ok": false, "data": null, "error": { "code": "not_found", "message": "..." } }

Read endpoints

Method	Path	Description
GET	/	API discovery + Make/Zapier hints
GET	/contests	List accessible contests (owned + collaborator)
GET	/contests/:id	Contest details + entry methods
GET	/contests/:id/stats	Entry totals and top contestants
GET	/contests/:id/contestants.csv	Unique contestants CSV
GET	/contests/:id/entries.csv	All entry rows CSV

Write endpoints (write scope)

Same validation and persistence as the dashboard builder. Mutations log with doorway: rest_v1 for support.

Method	Path	Description
POST	/contests	Create contest (blank or from draft body)
PATCH	/contests/:id	Update fields or status (e.g. go live)
POST	/contests/:id/sync	Full reconcile from draft (assistant parity)
POST	/contests/:id/entry-methods	Add entry method
PATCH	/contests/:id/entry-methods/:entryMethodId	Update entry method
DELETE	/contests/:id/entry-methods/:entryMethodId	Remove entry method
POST	/contests/:id/prizes	Add prize
PATCH	/contests/:id/prizes/:prizeId	Update prize
DELETE	/contests/:id/prizes/:prizeId	Remove prize

Example — create contest

curl -X POST -H "Authorization: Bearer rf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Summer Giveaway"}' \
  https://app.rewardsfuel.com/api/v1/contests

Example — list contests

curl -H "Authorization: Bearer rf_live_YOUR_KEY" \
  https://app.rewardsfuel.com/api/v1/contests

Webhook management

Register outbound hooks under /webhooks (requires hooks scope). See the webhooks guide for event types and Make.com setup.

Make.com (polling)

1. Add an HTTP module with Bearer token auth.
2. Call GET /contests or GET /contests/:id/stats.
3. Parse the data field from the JSON response.

For new entrants and winners in real time, prefer webhooks over polling stats.

Zapier

• Polling: Webhooks by Zapier (GET) or custom Zap with Bearer token
• Real-time: Zapier Catch Hook URL registered via POST /webhooks

Rate limits

• REST v1: 120 requests/minute per API key
• MCP: 60 tool calls/minute per API key

Responses include X-RateLimit-Remaining. On 429, wait for Retry-After.

Security

• Account scope is derived from your API key only — never pass account_id or user_id.
• Contest IDs are validated against your accessible contests.
• Keys are masked in the dashboard after creation; revoke unused keys promptly.

Generate keys in Account → API keys & integrations. AI agents should use MCP instead of REST. Need help? Contact us.