API reference

All endpoints live under https://sparka.io. Requests and responses are JSON (Content-Type: application/json). Field names are snake_case, timestamps are RFC 3339 in UTC, and durations carry their unit in the name (time_limit_s).

• Strict input. Unknown request fields are rejected with validation_failed, so a typo fails at save time, not on stage.
• Tolerant output. Responses may gain fields at any time; ignore the ones you don't know.
• Errors share one shape, described on the Errors page. Every response carries a Sparka-Request-Id header; quote it when you write to support.
• Lists take limit (1–100, default 20) and cursor, and return next_cursor (null on the last page). Newest first.
• Retries. POST /v1/presentations and POST /v1/keys accept an Idempotency-Key header, so a retried request never creates two.
• Compatibility. Changes under /v1/ only add things. A breaking change would get a new path prefix and at least six months' notice.

Presentations

Save, read, list and delete presentations (title, settings, questions).

• GET /v1/presentations List presentations
• POST /v1/presentations Create a presentation
• GET /v1/presentations/{presentation_id} Read a presentation
• PUT /v1/presentations/{presentation_id} Replace a presentation
• DELETE /v1/presentations/{presentation_id} Delete a presentation
• POST /v1/validate Validate without saving
• GET /v1/question-types List question types and their schemas

Sessions

Start, resume, inspect and end live sessions; read results.

• GET /v1/presentations/{presentation_id}/sessions List a presentation's sessions
• POST /v1/presentations/{presentation_id}/sessions Start or resume the live session
• GET /v1/sessions/{session_id} Session status
• POST /v1/sessions/{session_id}/end End a session
• GET /v1/sessions/{session_id}/results Session results

Join

Participant PIN lookup and join, called by the join page.

• GET /v1/pins/{pin} Look up a PIN
• POST /v1/pins/{pin}/join Join a session

Account & keys

Plan, limits, usage and secret-key management.

• GET /v1/account Plan, limits and usage
• GET /v1/keys List secret keys
• POST /v1/keys Create a secret key
• DELETE /v1/keys/{key_id} Revoke a secret key

Billing

Stripe Checkout and customer-portal links.

• POST /v1/billing/checkout Get a Checkout link
• POST /v1/billing/portal Get a customer-portal link

MCP

The MCP endpoint and the OAuth discovery documents MCP clients read.

• POST /mcp MCP endpoint (JSON-RPC)
• GET /.well-known/oauth-protected-resource Protected resource metadata (RFC 9728)
• GET /.well-known/oauth-protected-resource/mcp Protected resource metadata for /mcp (RFC 9728)
• GET /.well-known/oauth-authorization-server Authorization server metadata (RFC 8414)