Build on the Voxpla API

Quick start

1. In Voxpla, open Settings and then API keys (owners and admins).
2. Create a key, choose its permissions and copy it. It is shown only once.
3. Send it in the Authorization header of every request.
4. Load the OpenAPI description into Postman, Insomnia or your code generator.

curl https://voxpla.eu/api/v1/key \
  -H "Authorization: Bearer vx_live_..."

Authentication

Every request needs the header Authorization: Bearer followed by the key. Keys start with vx_live_ (vx_test_ outside production). Voxpla stores only a fingerprint of the key and its first characters for display. A lost key cannot be recovered: create a new one and revoke the old one.

Authorization: Bearer vx_live_3kQ9...

• A missing, unknown, expired or revoked key returns 401.
• When the organization's plan no longer includes the API, keys return 402 plan_required.
• The API does not accept browser sessions, and keys do not work in the web app.
• Every write call is recorded in the audit log together with the key that made it.

Scopes

Every key can read. Give a key more permissions only when an integration needs them.

read

List and read events, sessions, questions, polls, results, analytics and CSV exports.

write

Create and edit events, change their status, create, launch and close polls.

moderate

Moderate questions: approve, hide, highlight, mark as answered, pin, archive and delete.

A call outside the key's scopes returns 403 insufficient_scope.

Rate limits

Each key may send 600 requests per minute. Above the limit the API answers 429 rate_limited with a Retry-After header in seconds. Wait that long, then try again.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{"error":"rate_limited","retryAfter":12}

Pagination

Lists return items and next_cursor. Ask for up to 100 items with limit (default 25) and pass next_cursor as cursor to get the next page. On the last page next_cursor is null. Cursors are opaque, do not build them yourself.

curl "https://voxpla.eu/api/v1/events?limit=100&cursor=djE6Y2x4..." \
  -H "Authorization: Bearer $VOXPLA_API_KEY"

{ "items": [ ... ], "next_cursor": null }

Errors

Errors are JSON objects with a stable code in the error field. Base your logic on the code, not on the HTTP reason text.

400 invalid

The request body or a parameter is invalid; issues lists the fields.

401 invalid_api_key

The key is missing, unknown or revoked (api_key_expired for an expired key).

402 plan_required

The organization's plan does not include the API.

403 insufficient_scope

The key does not have the permission this call needs.

404 not_found

The object does not exist in your organization.

429 rate_limited

Too many requests; wait for the number of seconds in Retry-After.

Endpoints

All paths are relative to https://voxpla.eu/api/v1

• GET/keyread

  The calling key, its permissions and organization.

• GET/eventsread

  Events of your organization, newest first, optionally filtered by status.

• POST/eventswrite

  Creates an event with one session. The join code is generated.

• GET/events/{id}read

  One event with its join code, participant link and settings.

• PATCH/events/{id}write

  Changes the name, time, time zone, language or settings.

• POST/events/{id}/statuswrite

  Switches the event to draft, live, ended or archived.

• GET/events/{id}/sessionsread

  Sessions (rooms, program blocks) of an event.

• GET/sessions/{id}/questionsread

  Questions of a session with votes and replies, optionally filtered by status.

• POST/questions/{id}/actionsmoderate

  Approves, hides, highlights, answers, pins, archives or deletes a question.

• GET/sessions/{id}/pollsread

  Polls of a session in their order.

• POST/sessions/{id}/pollswrite

  Creates a poll, word cloud, rating, quiz question or another poll type.

• POST/polls/{id}/activatewrite

  Launches a poll. The running poll of the session closes.

• POST/polls/{id}/closewrite

  Closes a poll.

• GET/polls/{id}/resultsread

  Aggregated results of a poll.

• GET/events/{id}/analyticsread

  Participants, engagement, timeline, top questions and poll results.

• GET/events/{id}/export.csvread

  CSV export of questions, polls, participants or survey answers.

Responses contain what a moderator sees. Anonymous participants stay anonymous: no response contains participant identities, tokens or projector links.

Webhooks

Instead of asking the API again and again, let Voxpla call you. Set up a webhook in Settings and then Integrations for event.started, question.approved, poll.closed and event.ended.

• Each delivery is an HTTPS POST signed in the X-Voxpla-Signature header (HMAC-SHA256 of the timestamp and the raw body).
• Reject deliveries older than 5 minutes and use X-Voxpla-Delivery to ignore duplicates.
• Failed deliveries are retried twice. After 10 failures in a row the webhook pauses until you switch it on again.

X-Voxpla-Event: poll.closed
X-Voxpla-Delivery: dlv_6b0c3f...
X-Voxpla-Signature: t=1793390000,v1=5f0c1a...

Examples

List live events

curl https://voxpla.eu/api/v1/events?status=live&limit=50 \
  -H "Authorization: Bearer $VOXPLA_API_KEY"

Create an event

curl -X POST https://voxpla.eu/api/v1/events \
  -H "Authorization: Bearer $VOXPLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"All hands","startsAt":"2026-11-20T09:00:00Z","locale":"en"}'

Create and launch a poll

curl -X POST https://voxpla.eu/api/v1/sessions/$SESSION_ID/polls \
  -H "Authorization: Bearer $VOXPLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"multiple_choice","title":"Lunch?","options":[{"label":"Pizza"},{"label":"Salad"}]}'

curl -X POST https://voxpla.eu/api/v1/polls/$POLL_ID/activate -H "Authorization: Bearer $VOXPLA_API_KEY"

Read the results

curl https://voxpla.eu/api/v1/polls/$POLL_ID/results -H "Authorization: Bearer $VOXPLA_API_KEY"

Approve a question

curl -X POST https://voxpla.eu/api/v1/questions/$QUESTION_ID/actions \
  -H "Authorization: Bearer $VOXPLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"approve"}'