For developers
Put a wheel in your workflow.
Create saved wheels from your server. Share a playable link, or control a wheel on your own website and receive its winner.
Free pilot · 2–100 text entries · 24-hour share links
Your account
Get an API key
Use an email address you can verify. Your key belongs on your server, never in an iframe or a public browser script.
Sign in or create a developer account to manage keys.
Signed in as
Verify your email first
Open the verification message in your inbox, then refresh your account here. Check your spam folder if it has not arrived.
Copy your key now
This is the only time the full key is shown. Save it in a server environment variable. Closing this box or signing out clears it from this page.
Your keys
Up to 10 active keys. New keys expire after 90 days. Revoking a key stops requests using it; your saved API wheels stay.
Close API account
Closing is permanent for this sign-in account. It deletes your API wheels and keys and disables their share links. You cannot reopen API access with this account. Your Firebase sign-in record and wheels saved in this browser are separate.
This API account is closed. Its keys and shared API wheels are disabled. Signing in again cannot reopen it.
Creating an account sends your email to Firebase Authentication. API account data is stored separately from browser-saved My Wheels. Read Privacy and Cookies for storage and deletion details.
Start on your server
Create a wheel and get its link
- Create a verified developer account and copy an API key.
- Set
CHOICESPIN_API_KEYin your server environment. - Send the request below. The response includes
data.wheel.id,data.share.urlanddata.share.embedUrl.
curl https://choicespin.com/api/v1/wheels \
-H "Authorization: Bearer $CHOICESPIN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: activity-wheel-001" \
--data '{"config":{"title":"Next activity","entries":["Drawing","Music","Reading"]},"share":true}'Generate a new Idempotency-Key for each intended create operation. Keep that same value when retrying the request, so a retry does not create another wheel. The example value is a placeholder.
Check the HTTP status and save the returned ETag. Send it as If-Match when replacing or deleting a wheel. API errors include error.code and a diagnostic requestId.
Version 1
Endpoints and limits
Base URL: https://choicespin.com/api/v1. Authenticate wheel-management requests with Authorization: Bearer <your key>.
| Request | What it does |
|---|---|
POST /wheels | Create a wheel; add share: true for a playable snapshot. |
GET /wheels | List your wheels, with bounded cursor pagination. |
GET /wheels/{id} | Read one saved wheel and its version. |
PUT /wheels/{id} | Replace a wheel using its current If-Match value. |
DELETE /wheels/{id} | Delete a wheel and disable its share links. |
POST /wheels/{id}/shares | Create a new 24-hour snapshot. |
DELETE /wheels/{id}/shares/{shareId} | Disable one share link. |
OpenAPI specification (JSON) describes request fields, responses and errors.
- 2–100 text entries; up to 80 Unicode characters per entry and title.
- 100 saved wheels and 100 active share snapshots per account.
- 60 management requests per minute; 20 mutations per minute and 1,000 per day, shared across your keys.
- 32 KiB request bodies. Encoded wheel configuration must also fit 6,000 characters.
- Spin time 1–15 seconds. This pilot has no image uploads, weighted entries or multiple-wheel projects.
Saved wheels remain until deleted. Shared links are unlisted snapshots that expire after 24 hours. Updating a saved wheel does not change an earlier link. Anyone with a link can open its names and settings. Deleting a wheel or disabling its link blocks the next read; a copy already loaded cannot be recalled. A 429 response includes Retry-After. Availability also depends on the pilot's shared traffic limits.
On your website
Control an embedded wheel
The embed builder works without an API key. For a server-created snapshot, use the returned embedUrl. Keep the sandbox and referrer policy in your iframe:
<iframe src="YOUR_EMBED_URL" title="Activity wheel"
width="600" height="600"
sandbox="allow-scripts allow-popups allow-popups-to-escape-sandbox"
referrerpolicy="strict-origin-when-cross-origin"></iframe>
<script src="https://choicespin.com/scripts/embed/embed-client.js"></script>After the frame exists, the optional helper waits for readiness and returns the correlated winner:
const wheel = ChoiceSpinEmbed.createClient(document.querySelector("iframe"));
await wheel.ready();
await wheel.setEntries(["Drawing", "Music", "Reading"]);
const result = await wheel.spin();
document.querySelector("#winner").textContent = result.winner;
// When your page no longer needs this wheel:
wheel.dispose();Available methods: ready, spin, setEntries, addEntry, removeWinner, reset, on and dispose. Embed edits affect that browser session, not the saved API wheel. Spin-result events are UI results, not certified draw receipts or a one-spin guarantee.