REST API Documentation

Authentication

Create an API key in Settings (up to 3 active keys). The plaintext key is shown only once — store it securely. Send it on every request as a Bearer token:

Authorization: Bearer vot_api_xxxxxxxxxxxxxxxx

Requests without a valid, active key receive 401 Unauthorized. If the account's plan is inactive, endpoints return 403 Forbidden. Keys can be rotated (instantly invalidates the old secret) or deleted at any time from Settings.

Conventions

All requests and responses use application/json.
Successful responses wrap the payload in a data field.
Errors use the envelope { "error": "<code>", "message": "<text>" }.
Timestamps are ISO‑8601 (UTC).

Endpoints

Method	Path	Description
`GET`	`/surveys`	List your surveys.
`POST`	`/surveys`	Create a survey.
`GET`	`/surveys/{id}`	Get a survey with its questions.
`PATCH`	`/surveys/{id}`	Update title, description, status, questions or settings.
`DELETE`	`/surveys/{id}`	Delete a survey and all its data.
`GET`	`/surveys/{id}/responses`	List responses (`?limit=`, `?offset=`).
`GET`	`/surveys/{id}/analysis`	Get cached AI analysis.
`POST`	`/surveys/{id}/analysis`	Generate whole-survey AI analysis (needs ≥3 responses).

Examples

List surveys

curl -H "Authorization: Bearer $VOTIRA_API_KEY" \
  https://votira.co/api/v1/surveys

Create a survey

curl -X POST https://votira.co/api/v1/surveys \
  -H "Authorization: Bearer $VOTIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Pricing validation","description":"Quick check","questions":[]}'

Fetch responses (paginated)

curl -H "Authorization: Bearer $VOTIRA_API_KEY" \
  "https://votira.co/api/v1/surveys/srv_123/responses?limit=50&offset=0"

Rate limits

Requests are rate limited per client. Read endpoints allow up to 600 requests/hour; writes and AI analysis are more tightly limited (AI generation is capped at 30/hour). Exceeding a limit returns 429 with the rate_limited error code — back off and retry.

Status codes

200 / 201 — success.
400 — invalid request body or parameters.
401 — missing or invalid API key.
403 — account plan inactive.
404 — resource not found.
422 — not enough data (e.g. fewer than 3 responses for analysis).
429 — rate limit exceeded.
502 — AI provider temporarily unavailable.