REST API v1
Read contest data, export CSV, and create or update contests over a versioned HTTP API. For real-time triggers, use outbound webhooks instead of polling.
Related: Integrations hub · Developer hub · Webhooks · MCP
Requirements
- Paid plan
- API key with
readscope (reads) orwritescope (mutations; also satisfiesread) 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)
- Add an HTTP module with Bearer token auth.
- Call
GET /contestsorGET /contests/:id/stats. - Parse the
datafield 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_idoruser_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.