{"openapi":"3.1.0","info":{"title":"Rewards Fuel Integrations API","version":"1.0.0","description":"REST API for Make.com, Zapier, and custom integrations.\n\nAccount scope is derived from your API key — never pass `account_id` or `user_id`.\n\nHuman-readable guide: https://rewardsfuel.com/developers/api\n\nInteractive explorer: append `/docs` to this server URL (e.g. /api/v1/docs)."},"servers":[{"url":"https://app.rewardsfuel.com/api/v1"}],"tags":[{"name":"Contests","description":"Contest reads and writes"},{"name":"Entry methods","description":"Requires write scope"},{"name":"Prizes","description":"Requires write scope"},{"name":"Export","description":"CSV downloads"},{"name":"Webhooks","description":"Outbound webhook registration (hooks scope)"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Rewards Fuel API key (`rf_live_…`). Scopes: `read` (reads), `write` (mutations, super-scope), `hooks`, `mcp`, `wp`. Paid plan required."}},"schemas":{"ApiError":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"ContestIdResponse":{"type":"object","nullable":true,"properties":{"contestId":{"type":"integer"}},"required":["contestId"]},"ContestCreateBody":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","maxLength":240}},"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","maxLength":240},"description":{"type":"string","nullable":true,"maxLength":50000},"terms":{"type":"string","nullable":true,"maxLength":100000},"rules":{"nullable":true},"startTime":{"anyOf":[{"type":"string"},{"type":"number"}]},"endTime":{"anyOf":[{"type":"string"},{"type":"number"}]},"timeZone":{"type":"string","nullable":true,"maxLength":120},"languageId":{"type":"integer","minimum":1,"maximum":99},"contestUrl":{"type":"string","nullable":true,"maxLength":2048},"status":{"type":"string","enum":["draft","live","ended","deleted"]},"autoSelectWinners":{"type":"boolean"},"autoNotifyWinners":{"type":"boolean"},"entryMethods":{"type":"array","items":{"type":"object","properties":{"methodType":{"type":"string","minLength":1,"maxLength":64},"label":{"type":"string","nullable":true,"maxLength":500},"url":{"type":"string","nullable":true,"maxLength":2048},"points":{"type":"integer","minimum":0,"maximum":10000}},"required":["methodType"]}},"prizes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","nullable":true,"maxLength":10000},"quantity":{"type":"integer","minimum":1,"maximum":10000}},"required":["name"]}},"appearance":{"nullable":true}}}]},"ContestPatchResponse":{"type":"object","nullable":true,"properties":{"contestId":{"type":"integer"},"changedFields":{"type":"array","items":{"type":"string"}}},"required":["contestId","changedFields"]},"ContestPatch":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":240},"status":{"type":"string","enum":["draft","live","ended","deleted"]},"startTime":{"type":"integer","nullable":true},"endTime":{"type":"integer","nullable":true},"timeZone":{"type":"string","nullable":true,"maxLength":120},"description":{"type":"string","nullable":true,"maxLength":50000},"terms":{"type":"string","nullable":true,"maxLength":100000},"ageRestriction":{"type":"integer","minimum":0,"maximum":120},"geoRestrictions":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"nullable":true}]},"displayWinners":{"anyOf":[{"type":"number","enum":[0]},{"type":"number","enum":[1]},{"type":"boolean"}]},"autoSelectWinners":{"anyOf":[{"type":"number","enum":[0]},{"type":"number","enum":[1]},{"type":"boolean"}]},"autoNotifyWinners":{"anyOf":[{"type":"number","enum":[0]},{"type":"number","enum":[1]},{"type":"boolean"}]},"filterBots":{"anyOf":[{"type":"number","enum":[0]},{"type":"number","enum":[1]},{"type":"boolean"}]},"contestUrl":{"type":"string","nullable":true,"maxLength":2048},"languageId":{"type":"integer","minimum":1,"maximum":99},"appearance":{"anyOf":[{"type":"string"},{"type":"object","additionalProperties":{"nullable":true}},{"nullable":true}]},"rulesJson":{"anyOf":[{"type":"string"},{"type":"object","additionalProperties":{"nullable":true}},{"nullable":true}]}},"additionalProperties":false},"ContestDraft":{"type":"object","properties":{"name":{"type":"string","maxLength":240},"description":{"type":"string","nullable":true,"maxLength":50000},"terms":{"type":"string","nullable":true,"maxLength":100000},"rules":{"nullable":true},"startTime":{"anyOf":[{"type":"string"},{"type":"number"}]},"endTime":{"anyOf":[{"type":"string"},{"type":"number"}]},"timeZone":{"type":"string","nullable":true,"maxLength":120},"languageId":{"type":"integer","minimum":1,"maximum":99},"contestUrl":{"type":"string","nullable":true,"maxLength":2048},"status":{"type":"string","enum":["draft","live","ended","deleted"]},"autoSelectWinners":{"type":"boolean"},"autoNotifyWinners":{"type":"boolean"},"entryMethods":{"type":"array","items":{"type":"object","properties":{"methodType":{"type":"string","minLength":1,"maxLength":64},"label":{"type":"string","nullable":true,"maxLength":500},"url":{"type":"string","nullable":true,"maxLength":2048},"points":{"type":"integer","minimum":0,"maximum":10000}},"required":["methodType"]}},"prizes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","nullable":true,"maxLength":10000},"quantity":{"type":"integer","minimum":1,"maximum":10000}},"required":["name"]}},"appearance":{"nullable":true}}},"EntryMethodIdResponse":{"type":"object","nullable":true,"properties":{"entryMethodId":{"type":"integer"}},"required":["entryMethodId"]},"EntryMethodCreate":{"type":"object","properties":{"methodType":{"type":"string","minLength":1,"maxLength":64,"description":"Entry method type id from Rewards Fuel catalog"},"label":{"type":"string","nullable":true,"maxLength":500},"url":{"type":"string","nullable":true,"maxLength":2048},"points":{"type":"integer","minimum":0,"maximum":10000},"sortOrder":{"type":"integer","minimum":0},"settings":{"type":"string","nullable":true,"maxLength":20000}},"required":["methodType"]},"EntryMethodPatch":{"type":"object","properties":{"label":{"type":"string","nullable":true,"maxLength":500},"url":{"type":"string","nullable":true,"maxLength":2048},"points":{"type":"integer","minimum":0,"maximum":10000},"sortOrder":{"type":"integer","minimum":0},"settings":{"type":"string","nullable":true,"maxLength":20000},"active":{"anyOf":[{"type":"number","enum":[0]},{"type":"number","enum":[1]}]}},"additionalProperties":false},"PrizeIdResponse":{"type":"object","nullable":true,"properties":{"prizeId":{"type":"integer"}},"required":["prizeId"]},"PrizeCreate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","nullable":true,"maxLength":10000},"quantity":{"type":"integer","minimum":1,"maximum":10000},"imageUrl":{"type":"string","nullable":true,"maxLength":2048},"prizeType":{"type":"string","enum":["physical","digital"]},"digitalContent":{"type":"string","nullable":true,"maxLength":500000}},"required":["name"]},"PrizePatch":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","nullable":true,"maxLength":10000},"quantity":{"type":"integer","minimum":1,"maximum":10000},"imageUrl":{"type":"string","nullable":true,"maxLength":2048},"prizeType":{"type":"string","enum":["physical","digital"]},"digitalContent":{"type":"string","nullable":true,"maxLength":500000}},"additionalProperties":false},"WebhookCreate":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["contest.created","contest.started","contest.ended","entry.created","entry.confirmed","contestant.created","winner.picked"]}},"label":{"type":"string","nullable":true,"maxLength":200},"contestId":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"enabled":{"type":"boolean"}},"required":["url"],"additionalProperties":false},"WebhookPatch":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["contest.created","contest.started","contest.ended","entry.created","entry.confirmed","contestant.created","winner.picked"]}},"label":{"type":"string","nullable":true,"maxLength":200},"contestId":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"enabled":{"type":"boolean"}},"additionalProperties":false}},"parameters":{}},"paths":{"/contests":{"get":{"tags":["Contests"],"summary":"List accessible contests","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"example":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Contest list","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","nullable":true,"properties":{}},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}},"post":{"tags":["Contests"],"summary":"Create contest (blank or from draft)","description":"Requires `write` scope. Blank body uses default schedule; draft body requires dates, entry methods, and prizes.","security":[{"BearerAuth":["write"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContestCreateBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ContestIdResponse"},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}}},"/contests/{contestId}":{"get":{"tags":["Contests"],"summary":"Get contest details","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"contestId","in":"path"}],"responses":{"200":{"description":"Contest","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","nullable":true,"properties":{"contest":{"type":"object","properties":{}}},"required":["contest"]},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}},"patch":{"tags":["Contests"],"summary":"Update contest fields or status","description":"Requires `write` scope. Set `status` to `live` to publish.","security":[{"BearerAuth":["write"]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"contestId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContestPatch"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ContestPatchResponse"},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}}},"/contests/{contestId}/sync":{"post":{"tags":["Contests"],"summary":"Full reconcile from draft","description":"Requires `write` scope. Same behavior as dashboard assistant sync.","security":[{"BearerAuth":["write"]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"contestId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContestDraft"}}}},"responses":{"200":{"description":"Sync result","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","nullable":true,"properties":{}},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}}},"/contests/{contestId}/stats":{"get":{"tags":["Contests"],"summary":"Contest entry stats","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"contestId","in":"path"}],"responses":{"200":{"description":"Stats","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","nullable":true,"properties":{"stats":{"type":"object","properties":{}}},"required":["stats"]},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}}},"/contests/{contestId}/contestants.csv":{"get":{"tags":["Export"],"summary":"Unique contestants CSV","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"contestId","in":"path"}],"responses":{"200":{"description":"CSV file","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/contests/{contestId}/entries.csv":{"get":{"tags":["Export"],"summary":"All entry rows CSV","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"contestId","in":"path"}],"responses":{"200":{"description":"CSV file","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/contests/{contestId}/entry-methods":{"post":{"tags":["Entry methods"],"summary":"Create entry method","security":[{"BearerAuth":["write"]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"contestId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntryMethodCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"$ref":"#/components/schemas/EntryMethodIdResponse"},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}}},"/contests/{contestId}/entry-methods/{entryMethodId}":{"patch":{"tags":["Entry methods"],"summary":"Update entry method","security":[{"BearerAuth":["write"]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"contestId","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"entryMethodId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntryMethodPatch"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","nullable":true,"properties":{}},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}},"delete":{"tags":["Entry methods"],"summary":"Delete entry method","security":[{"BearerAuth":["write"]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"contestId","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"entryMethodId","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","nullable":true,"properties":{}},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}}},"/contests/{contestId}/prizes":{"post":{"tags":["Prizes"],"summary":"Create prize","security":[{"BearerAuth":["write"]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"contestId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrizeCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"$ref":"#/components/schemas/PrizeIdResponse"},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}}},"/contests/{contestId}/prizes/{prizeId}":{"patch":{"tags":["Prizes"],"summary":"Update prize","security":[{"BearerAuth":["write"]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"contestId","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"prizeId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrizePatch"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","nullable":true,"properties":{}},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}},"delete":{"tags":["Prizes"],"summary":"Delete prize","security":[{"BearerAuth":["write"]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"contestId","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"prizeId","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","nullable":true,"properties":{}},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}}},"/webhooks/events":{"get":{"tags":["Webhooks"],"summary":"List webhook event types","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Event catalog","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","nullable":true,"properties":{}},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List registered outbound webhooks","description":"Requires `hooks` scope.","security":[{"BearerAuth":["hooks"]}],"responses":{"200":{"description":"Webhook list","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","nullable":true,"properties":{}},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}},"post":{"tags":["Webhooks"],"summary":"Register outbound webhook URL","description":"Requires `hooks` scope. Signing secret returned once at creation.","security":[{"BearerAuth":["hooks"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","nullable":true,"properties":{}},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}}},"/webhooks/{webhookId}":{"patch":{"tags":["Webhooks"],"summary":"Update webhook","security":[{"BearerAuth":["hooks"]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"webhookId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPatch"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","nullable":true,"properties":{}},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete webhook","security":[{"BearerAuth":["hooks"]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"webhookId","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","nullable":true,"properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}}},"/webhooks/{webhookId}/test":{"post":{"tags":["Webhooks"],"summary":"Send test payload to webhook URL","security":[{"BearerAuth":["hooks"]}],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":true,"name":"webhookId","in":"path"}],"responses":{"200":{"description":"Delivered","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","nullable":true,"properties":{"delivered":{"type":"boolean","enum":[true]}},"required":["delivered"]},"error":{"$ref":"#/components/schemas/ApiError"}},"required":["ok","data","error"]}}}}}}}}}