Developers

The Movie Night Polls REST API lets you create and manage polls programmatically. Use it to build chat-platform integrations, internal tools, or third-party clients.

Authentication

Every write request must include a personal API token in the Authorization header. Public reads of public polls do not require a token.

Issue tokens from your account page. API tokens require a Pro subscription. Tokens are shown in full once at issuance — store them somewhere safe; we keep only a hash.

Authorization: Bearer mnp_live_<your-token>

Base URL

https://www.movienightpolls.com

Endpoints

Method	Path	Auth	Rate limit
POST	/api/v1/polls	Bearer	10 / minute / token
GET	/api/v1/polls/{id}	Bearer or public	120 / minute (per token, or per IP if anonymous)
POST	/api/v1/polls/{id}/votes	Bearer	60 / minute / token / poll
POST	/api/v1/polls/{id}/close	Bearer	30 / minute / token
DELETE	/api/v1/polls/{id}	Bearer	30 / minute / token

Full schemas in the OpenAPI spec.

Quick start

Create a poll

curl -X POST https://www.movienightpolls.com/api/v1/polls \
  -H "Authorization: Bearer mnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "pollTitle": "Friday horror night",
    "movieOptions": [
      {"id": 694, "title": "The Shining", "release_date": "1980-05-23", "image_url": "https://image.tmdb.org/t/p/w500/b6ko0IKC8MdYBBPkkA1aBPLe2yz.jpg"},
      {"id": 539, "title": "Psycho", "release_date": "1960-06-22", "image_url": "https://image.tmdb.org/t/p/w500/yz4QVqPx3h1hD1DfqqQkCq3rmxW.jpg"}
    ]
  }'

Cast a vote

curl -X POST https://www.movienightpolls.com/api/v1/polls/{id}/votes \
  -H "Authorization: Bearer mnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "votes": [{ "voterUid": "discord:1234567890", "movieId": 694 }] }'

For chat-platform integrations, prefix voterUid with the platform name (e.g. discord:1234567890) so identifiers don't collide across platforms.

Limits

Request body: max 50 KB.
Movies per poll: 6 free, 25 Pro.
Polls per month: 5 free, unlimited Pro.
Active tokens per user: 5.
Rate limits per endpoint listed above. Each response includes X-RateLimit-Remaining and friends.

Errors

Error responses are JSON: { "error": "...", "code": "..." }. Validation errors also include an issues[] array with the offending field paths.

Code	HTTP	Meaning
INVALID_INPUT	400	Body failed schema validation. See `issues[]`.
UNAUTHORIZED	401	Missing, malformed, or revoked bearer token.
FORBIDDEN	403	Authenticated but not allowed (not owner, not Pro, etc).
MONTHLY_LIMIT_REACHED	403	Free tier hit the 5-poll monthly cap.
NOT_FOUND	404	Poll doesn't exist or isn't visible to you.
DUPLICATE_VOTE	409	(voterUid, movieId) already voted on this poll.
PAYLOAD_TOO_LARGE	413	Body exceeded 50 KB.
RATE_LIMITED	429	Slow down. See Retry-After.
INTERNAL_ERROR	500	Something broke on our end.

Versioning

All routes live under /api/v1. Breaking changes ship under a new prefix; v1 stays stable.

Help

Bug reports and feature requests: support page.