Developers

Spin or Flip API

Programmatically create wheels, record spins, and integrate random decisions into any product — from classroom tools to sports bracket apps.

Early access. The API is in active development. Endpoints below are the planned surface area. Contact contact@spinorflip.com to get API access and share what you're building.

Overview

The Spin or Flip REST API lets you create and manage wheels, record spin events, retrieve results, and trigger AI-powered wheel generation via Claude. Responses are JSON. All endpoints require a Pro API key.

🏫

LMS & classroom tools

Pull student rosters from your LMS, create a wheel per class, and record participation spins — automatically, without manual setup.

🏆

Sports & bracket apps

Generate tournament matchups or draft-order wheels dynamically from live league data and embed the results in your app.

🤖

AI-powered wheel creation

Send a prompt to the generate endpoint and get a wheel back — Claude picks the options. Great for chatbots, Slack bots, and voice apps.

📊

Analytics & reporting

Read spin results via API to build your own dashboards, audit trails, or engagement reports on top of Spin or Flip data.

🎮

Games & experiences

Use the spin endpoint in-game to add a verifiable random element — useful for party games, reward mechanics, or live-event entertainment.

🔗

Shared spaces (coming soon)

Create a shared wheel space for a group. Members join via link, see spins in real time, and the host controls the experience.

Authentication

All API requests are authenticated with a bearer token. Generate your API key in Settings → API inside the app (Pro required).

Pass your key as an Authorization header on every request:
Authorization: Bearer sk_live_<your_key>

shell 
curl https://www.spinorflip.com/api/v1/wheels \
  -H "Authorization: Bearer sk_live_<your_key>" \
  -H "Content-Type: application/json"

Base URL

base url 
https://www.spinorflip.com/api/v1

Wheels

Create, read, update, and delete wheels. Each wheel has a title, a list of options, and an optional background.

GET
/wheels
List all wheels for the authenticated user.
POST
/wheels
Create a new wheel with a title and options array.
GET
/wheels/:id
Get a specific wheel by ID.
PUT
/wheels/:id
Update a wheel's title, options, or background.
DELETE
/wheels/:id
Delete a wheel permanently.
POST /wheels — example 
{
  "title": "Friday Lunch",
  "options": [
    "Thai", "Pizza", "Sushi", "Tacos", "Burgers"
  ]
}
Response 201 
{
  "id": "whl_a1b2c3d4",
  "title": "Friday Lunch",
  "options": ["Thai", "Pizza", "Sushi", "Tacos", "Burgers"],
  "url": "https://www.spinorflip.com/?wheel=whl_a1b2c3d4",
  "created_at": "2026-05-01T14:22:00Z"
}

Spins

Record a spin programmatically and get a random result, or read the spin history for a wheel.

POST
/wheels/:id/spin
Spin a wheel — returns a random option from the wheel's list.
GET
/wheels/:id/spins
Get the full spin history for a wheel.
POST /wheels/:id/spin — response 
{
  "spin_id": "spn_x9y8z7",
  "wheel_id": "whl_a1b2c3d4",
  "result": "Sushi",
  "spun_at": "2026-05-01T14:25:10Z"
}

AI Generate Pro

Send a natural-language prompt and Claude generates a wheel for you. The endpoint returns a ready-to-use wheel object with options filled in.

POST
/generate
Generate wheel options from a prompt using Claude AI.
POST /generate — example 
{
  "prompt": "Team icebreaker questions for a remote engineering team",
  "count": 8
}
Response 200 
{
  "title": "Icebreaker Questions",
  "options": [
    "What's your non-work superpower?",
    "What tool do you wish existed?",
    "Best meeting you've ever had — what made it great?",
    "What are you reading or watching right now?",
    // ... 4 more
  ],
  "model": "claude-sonnet-4-6"
}