DOCS · REST API

The Rafflex
REST API

Create, publish and finalize raffles, manage templates and read entries and winners from your own tools. Included with Rafflex Pro.

Open the API referenceIn-app guide

Quick start

  1. Make sure the project owner has an active Pro plan.
  2. In the app, open Managed projects → your project → API access and create a key with the scopes you need. The secret is shown once.
  3. Send it in the X-Api-Key header.
curl https://api.rafflex.xyz/api/v1/projects \
  -H "X-Api-Key: $RAFFLEX_API_KEY"

The OpenAPI document is at /openapi/v1.json and the interactive reference at /docs on the API host.

Keys and scopes

Keys belong to a project and to the team member who created them. Every request checks the owner’s plan, the key’s expiry and revocation, and the creator’s current role. A project can have up to five active keys. Available scopes: projects:read, projects:write, raffles:read, raffles:write, entries:read, winners:read, templates:read, templates:write.

Raffle lifecycle

Creating a raffle produces a draft. PUT replaces a draft; PATCH replaces only the fields you send (nested objects and arrays are replaced whole). Publish with POST …/publish; finalize early with POST …/finalize. Only drafts can be deleted. Creating from a template copies its saved configuration and accepts overrides for name, reward project, network, schedule and winner count.

Limits

  • 60 requests/minute per project, at most 10 of them writes; Retry-After on 429.
  • JSON bodies up to 1 MiB; images up to 10 MiB.
  • Per raffle: up to 10,000 allowlist addresses, 20 NFT/token conditions, 10 Discord servers with 100 roles each, and 9 X conditions.
  • Pagination: page from 1, pageSize 1–100.
  • JSON writes accept an Idempotency-Key header, replayed for 24 hours.

Endpoints

MethodPathPurposeScope
GET/api/v1/projectsList projects the key can accessprojects:read
GET/api/v1/projects/{projectId}Project detailsprojects:read
PUT/api/v1/projects/{projectId}Update a projectprojects:write
GET/api/v1/projects/{projectId}/statsProject statisticsprojects:read
GET/api/v1/projects/{projectId}/reward-projectsSearch reward projectsprojects:read
POST/api/v1/projects/{projectId}/reward-projectsAdd a reward projectprojects:write
GET/api/v1/projects/{projectId}/rafflesList a project’s rafflesraffles:read
POST/api/v1/projects/{projectId}/rafflesCreate a draft raffleraffles:write
GET/api/v1/raffles/{raffleId}Raffle detailsraffles:read
PUT/api/v1/raffles/{raffleId}Replace a draftraffles:write
PATCH/api/v1/raffles/{raffleId}Update supplied fieldsraffles:write
DELETE/api/v1/raffles/{raffleId}Delete a draftraffles:write
POST/api/v1/raffles/{raffleId}/publishPublish a draftraffles:write
POST/api/v1/raffles/{raffleId}/finalizeFinalize earlyraffles:write
POST/api/v1/raffles/{raffleId}/imageUpload the raffle imageraffles:write
GET/api/v1/raffles/{raffleId}/statsAggregate raffle statisticsraffles:read
GET/api/v1/raffles/{raffleId}/entriesEntriesentries:read
GET/api/v1/raffles/{raffleId}/winnersWinnerswinners:read
GET/api/v1/raffles/{raffleId}/winner-deliveriesWinner delivery statuswinners:read
GET/api/v1/projects/{projectId}/raffle-templatesList templatestemplates:read
POST/api/v1/projects/{projectId}/raffle-templatesSave a templatetemplates:write
POST/api/v1/projects/{projectId}/raffle-templates/{templateId}/rafflesCreate a raffle from a templatetemplates:read + raffles:write
GET/api/v1/usageCurrent verification usage—

API questions

Does Rafflex have an API?

Yes. Rafflex Pro includes a REST API under https://api.rafflex.xyz/api/v1 for projects, raffles, templates, entries and winners. Authenticate with a project API key in the X-Api-Key header.

Which plan includes API access?

The project owner needs active Host Pro access through a paid subscription, an active Pro trial, or verified holdings of 9+ Compact Games NFTs. Team members do not need their own Pro plan.

Does the API support webhooks?

No. Poll the raffle, entries, winners and winner-delivery endpoints instead.

What are the rate limits?

60 authenticated requests per minute per project, including at most 10 writes. Rate-limited responses include a Retry-After header.

MCP server

Connect ChatGPT, Claude or Cursor to Rafflex and draft raffles in conversation.

AI raffles via MCP

Draft and publish raffles from ChatGPT, Claude or any MCP-compatible assistant.

YOUR NEXT DROP

Run it on Rafflex

Random draw or FCFS, verified entry actions, and a winner list that gets where it needs to go. Try every Pro feature free for 7 days — no card required.

Launch your first raffle Browse live raffles