API reference

The PollGarden REST API lets you create and manage polls programmatically. Requires a Premium plan and an API key.

Authentication

Create a key in your dashboard, then send it as a Bearer token. Keys are secret — never ship them in a browser.

curl https://pollgarden.com/api/v1/me \
  -H "Authorization: Bearer pk_live_your_key_here"

Endpoints

Method	Path	Description
GET	/api/v1/me	Your plan and rate limits.
GET	/api/v1/polls	List your polls (cursor, limit≤100).
POST	/api/v1/polls	Create a poll (same schema as the builder).
GET	/api/v1/polls/:id	Poll detail with options.
PATCH	/api/v1/polls/:id	Edit title/description.
DELETE	/api/v1/polls/:id	Soft-delete a poll.
POST	/api/v1/polls/:id/close	Close a poll.
GET	/api/v1/polls/:id/results	Aggregated results.
GET	/api/v1/polls/:id/votes	Paginated raw votes.

Create a poll

curl -X POST https://pollgarden.com/api/v1/polls \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "single",
    "title": "Best pizza topping?",
    "visibility": "public",
    "categoryId": "<uuid>",
    "options": [{"label":"Margherita"},{"label":"Pepperoni"}]
  }'

Response:

{ "data": { "id": "...", "slug": "abc12xyz", "url": "/p/abc12xyz" } }

Errors

Every error is { "error": { "code", "message" } }.

Code	HTTP	Meaning
unauthorized	401	Missing/invalid API key.
forbidden	403	Banned account.
plan_required	403	Premium plan required.
not_found	404	Resource not found or not yours.
validation_error	422	Body failed validation.
rate_limited	429	Too many requests (see Retry-After).

Rate limits

60 requests/minute and 5,000/day per key. Responses include X-RateLimit-Limit, -Remaining and -Reset; a 429 includes Retry-After.