Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.
TypeScript i18nextnext-authnextjspostgresqlprismareact-emailt3-stacktailwindcsstrpcturborepotypescriptzod
{
"openapi": "3.1.0",
"info": {
"title": "Rallly API",
"description": "## Versioning\n\n`v1` is stable. Additive changes (new endpoints, new optional fields) may land on this path at any time; breaking changes only arrive under a new version prefix.\n\n## Rate limits\n\nAll endpoints share two limits per space: **60 requests per minute** and **5000 requests per day**. Both are fixed windows that open with the first request and reset when they expire. Both limits are per space, not per API key, so creating additional keys does not increase throughput.\n\nEvery response from an authenticated request includes the standard `RateLimit-*` headers. Responses sent before the limiter runs (`401`, `403`, and the maintenance `503`) do not. `RateLimit-Policy` lists both limits; `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` describe whichever limit is closest to being exhausted. When either limit is exceeded the API responds with `429 Too Many Requests`, a `RATE_LIMIT_EXCEEDED` error body, and a `Retry-After` header indicating how many seconds to wait before retrying.\n\nIf the rate limit store cannot be reached the API fails closed and responds with `503 Service Unavailable`, a `SERVICE_UNAVAILABLE` error body, and a `Retry-After` header.\n\n## Dates and times\n\nEvery poll has a `kind`. A `date` poll offers calendar days: each option carries a `date` in `YYYY-MM-DD` format, which is a floating date with no time component and no timezone, so never convert it through a timezone. A `time` poll offers time slots: each option carries a `startTime` as an ISO 8601 instant in UTC and a `duration` in minutes; convert `startTime` into the poll's `timeZone` (or the viewer's) for display. Timestamps such as `createdAt` and `updatedAt` are always ISO 8601 instants in UTC.\n\n## Request bodies\n\nRequest bodies are validated strictly: a field that is not part of the documented schema is rejected with `VALIDATION_ERROR` rather than ignored, so a misspelt setting never silently falls back to its default.\n\n## Enums\n\nVote types are an open set. The built-in values are `yes`, `ifNeedBe` and `no`; new types may be added without a version change, so clients must tolerate values they do not recognise. `status` and `kind` are closed sets.\n\n## Lists\n\nList endpoints return the items in `data`. `GET /polls` is paginated: it returns a `nextCursor` beside `data`; pass it as the `cursor` query parameter to fetch the next page, and it is `null` on the last page. `GET /polls/:pollId/participants` returns every participant in one response.\n\n## Errors\n\nEvery failure is `application/json` with the shape `{ \"error\": { \"code\", \"message\" } }`. `code` is stable and safe to branch on; `message` is human-readable and may change. `VALIDATION_ERROR` messages name each offending field.\n\n| Status | Code | When |\n| --- | --- | --- |\n| 400 | `VALIDATION_ERROR` | The body or query string did not match the schema, contained an unknown field, or the body was not valid JSON |\n| 400 | `INVALID_AUTHORIZATION_HEADER` | The `Authorization` header is not `Bearer <key>` |\n| 400 | `ORGANIZER_NOT_MEMBER` | The organizer email is not a member of the space |\n| 400 | `TOO_MANY_OPTIONS` | More than the maximum number of poll options |\n| 400 | `CONFERENCING_UNAVAILABLE` | The requested video call provider is not offered on this instance |\n| 400 | `CONFERENCING_NOT_CONNECTED` | The organizer has not connected an account for the requested video call provider |\n| 400 | `INAPPROPRIATE_CONTENT` | The title, description, location or video call was flagged by content moderation |\n| 401 | `UNAUTHORIZED` | The API key is missing, invalid, expired or revoked, or its owner is banned |\n| 403 | `SPACE_NOT_PRO` | The space behind the key has no Pro subscription |\n| 404 | `NOT_FOUND` | No route matches the method and path |\n| 404 | `POLL_NOT_FOUND` | The poll does not exist or belongs to another space |\n| 404 | `PARTICIPANT_NOT_FOUND` | The participant does not exist or belongs to another poll |\n| 429 | `RATE_LIMIT_EXCEEDED` | A rate limit window is exhausted |\n| 503 | `SERVICE_UNAVAILABLE` | Maintenance, or the rate limit store cannot be reached |\n| 500 | `INTERNAL_ERROR` | Unexpected failure; the request id is logged |",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.rallly.co"
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
},
"schemas": {
"Poll": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "Xk3pQ9vLm2Ab"
},
"title": {
"type": "string",
"example": "Team sync"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"example": "Pick a time that works for everyone"
},
"location": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"example": "Conference Room A"
},
"conferencing": {
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "meet"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "zoom"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "teams"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "webex"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "custom"
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"uri": {
"type": "string",
"format": "uri"
}
},
"required": [
"provider",
"label"
]
}
]
},
{
"type": "null"
}
],
"description": "The video call for the event, or `null`. A `meet`, `zoom`, `teams` or `webex` entry has no link until the poll is finalized; a `custom` entry carries the organizer's label and, when given, the link.",
"example": {
"provider": "zoom"
}
},
"timeZone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"example": "Europe/London"
},
"status": {
"$ref": "#/components/schemas/PollStatus"
},
"kind": {
"$ref": "#/components/schemas/PollKind"
},
"createdAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-10T12:00:00.000Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "When the poll was last modified. Changes when the poll's details, settings or status change.",
"example": "2025-01-12T08:30:00.000Z"
},
"organizer": {
"anyOf": [
{
"$ref": "#/components/schemas/PollOrganizer"
},
{
"type": "null"
}
],
"description": "The space member the poll belongs to. `null` when the organizer's account no longer exists."
},
"requireEmail": {
"type": "boolean",
"description": "Whether participants must provide their email address",
"example": false
},
"hideParticipants": {
"type": "boolean",
"description": "Whether participant names are hidden from other participants",
"example": false
},
"hideScores": {
"type": "boolean",
"description": "Whether vote counts are hidden from participants",
"example": false
},
"disableComments": {
"type": "boolean",
"description": "Whether the comments section is disabled",
"example": true
},
"allowTentativeVotes": {
"type": "boolean",
"description": "Whether participants may cast the tentative \"if need be\" vote",
"example": true
},
"participantCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Number of participants who have responded to the poll",
"example": 3
},
"options": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PollOption"
}
},
"adminUrl": {
"type": "string",
"example": "https://app.rallly.co/poll/Xk3pQ9vLm2Ab"
},
"inviteUrl": {
"type": "string",
"example": "https://rallly.co/invite/Xk3pQ9vLm2Ab"
}
},
"required": [
"id",
"title",
"description",
"location",
"conferencing",
"timeZone",
"status",
"kind",
"createdAt",
"updatedAt",
"organizer",
"requireEmail",
"hideParticipants",
"hideScores",
"disableComments",
"allowTentativeVotes",
"participantCount",
"options",
"adminUrl",
"inviteUrl"
]
},
"PollStatus": {
"type": "string",
"enum": [
"open",
"closed",
"scheduled",
"canceled"
]
},
"PollKind": {
"type": "string",
"enum": [
"date",
"time"
],
"description": "Whether the poll offers calendar dates (`date`) or time slots (`time`). Determines which option shape the poll uses: every option in a `date` poll has a `date`, every option in a `time` poll has a `startTime` and `duration`.",
"example": "time"
},
"PollOrganizer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cm3f7d1qa0000t2k9c6b8h4jr"
},
"name": {
"type": "string",
"example": "John Doe"
},
"email": {
"type": "string",
"format": "email",
"example": "[email protected]"
},
"image": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"example": "https://cdn.rallly.co/avatars/cm3f7d1qa0000t2k9c6b8h4jr.jpg"
}
},
"required": [
"id",
"name",
"email",
"image"
]
},
"PollOption": {
"anyOf": [
{
"$ref": "#/components/schemas/DateOption"
},
{
"$ref": "#/components/schemas/TimeOption"
}
],
"description": "A poll option. The shape follows the poll's `kind`: a `DateOption` for `date` polls, a `TimeOption` for `time` polls."
},
"DateOption": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cm5h8x2k40000q9l4f7e2d3an"
},
"date": {
"type": "string",
"format": "date",
"description": "Calendar date in YYYY-MM-DD format. All-day options are floating dates with no time component and no timezone.",
"example": "2025-01-15"
}
},
"required": [
"id",
"date"
],
"description": "An all-day option. Only present in polls with `kind: date`."
},
"TimeOption": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cm5h8x2k40000q9l4f7e2d3an"
},
"startTime": {
"type": "string",
"format": "date-time",
"description": "Start of the slot as an ISO 8601 instant in UTC.",
"example": "2025-01-15T09:00:00.000Z"
},
"duration": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Duration in minutes.",
"example": 30
}
},
"required": [
"id",
"startTime",
"duration"
],
"description": "A time slot. Only present in polls with `kind: time`."
},
"PollResponse": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Poll"
}
},
"required": [
"data"
]
},
"ErrorResponse": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code. The full list is in the API description.",
"example": "VALIDATION_ERROR"
},
"message": {
"type": "string",
"description": "Human-readable explanation. For `VALIDATION_ERROR` it names each offending field, e.g. `title: Invalid input: expected string, received undefined; dates.0: Invalid ISO date`.",
"example": "title: Invalid input: expected string, received undefined"
}
},
"required": [
"code",
"message"
]
}
},
"required": [
"error"
]
},
"CreateDatePollInput": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Team sync"
},
"kind": {
"type": "string",
"const": "date",
"description": "Participants vote on whole days."
},
"description": {
"example": "Pick a time that works for everyone",
"type": "string",
"maxLength": 1000
},
"location": {
"description": "Where the event takes place, as free text.",
"example": "Conference Room A",
"type": "string",
"maxLength": 255
},
"conferencing": {
"description": "The video call for the event. `meet`, `zoom`, `teams` and `webex` need the organizer to have connected that account in their Conferencing settings; the meeting link is created when the poll is finalized. `custom` names any call, with an optional link participants join with.",
"examples": [
{
"provider": "zoom"
},
{
"provider": "custom",
"label": "Microsoft Teams",
"uri": "https://teams.microsoft.com/l/meetup-join/abc"
}
],
"oneOf": [
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "meet"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "zoom"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "teams"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "webex"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "custom"
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"uri": {
"type": "string",
"format": "uri"
}
},
"required": [
"provider",
"label"
]
}
]
},
"requireEmail": {
"description": "Require participants to provide their email address",
"example": true,
"type": "boolean"
},
"hideParticipants": {
"description": "Hide participant names from other participants",
"example": false,
"type": "boolean"
},
"hideScores": {
"description": "Hide vote counts from participants",
"example": false,
"type": "boolean"
},
"disableComments": {
"description": "Disable the comments section. Defaults to true: new polls have comments disabled unless this is set to false.",
"example": false,
"type": "boolean"
},
"allowTentativeVotes": {
"description": "Allow participants to answer \"if need be\" as well as yes and no. Defaults to true.",
"example": true,
"type": "boolean"
},
"organizer": {
"description": "Organizer of the poll. Defaults to the space owner if not provided. The organizer must be a member of the space.",
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Email address of the organizer",
"example": "[email protected]"
}
},
"required": [
"email"
],
"additionalProperties": false
},
"options": {
"minItems": 1,
"type": "array",
"items": {
"$ref": "#/components/schemas/DateOptionInput"
},
"description": "Calendar days to offer. Dates are floating calendar days with no timezone, so never convert them through one. Duplicates are removed."
}
},
"required": [
"title",
"kind",
"options"
],
"additionalProperties": false,
"title": "Date poll"
},
"DateOptionInput": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "Calendar day to offer, as a floating `YYYY-MM-DD` date.",
"example": "2027-03-01"
}
},
"required": [
"date"
],
"additionalProperties": false,
"title": "Date option",
"description": "One all-day option. The same shape `DateOption` returns."
},
"CreateTimePollInput": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Team sync"
},
"kind": {
"type": "string",
"const": "time",
"description": "Participants vote on time slots."
},
"description": {
"example": "Pick a time that works for everyone",
"type": "string",
"maxLength": 1000
},
"location": {
"description": "Where the event takes place, as free text.",
"example": "Conference Room A",
"type": "string",
"maxLength": 255
},
"conferencing": {
"description": "The video call for the event. `meet`, `zoom`, `teams` and `webex` need the organizer to have connected that account in their Conferencing settings; the meeting link is created when the poll is finalized. `custom` names any call, with an optional link participants join with.",
"examples": [
{
"provider": "zoom"
},
{
"provider": "custom",
"label": "Microsoft Teams",
"uri": "https://teams.microsoft.com/l/meetup-join/abc"
}
],
"oneOf": [
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "meet"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "zoom"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "teams"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "webex"
}
},
"required": [
"provider"
]
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"const": "custom"
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"uri": {
"type": "string",
"format": "uri"
}
},
"required": [
"provider",
"label"
]
}
]
},
"requireEmail": {
"description": "Require participants to provide their email address",
"example": true,
"type": "boolean"
},
"hideParticipants": {
"description": "Hide participant names from other participants",
"example": false,
"type": "boolean"
},
"hideScores": {
"description": "Hide vote counts from participants",
"example": false,
"type": "boolean"
},
"disableComments": {
"description": "Disable the comments section. Defaults to true: new polls have comments disabled unless this is set to false.",
"example": false,
"type": "boolean"
},
"allowTentativeVotes": {
"description": "Allow participants to answer \"if need be\" as well as yes and no. Defaults to true.",
"example": true,
"type": "boolean"
},
"organizer": {
"description": "Organizer of the poll. Defaults to the space owner if not provided. The organizer must be a member of the space.",
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Email address of the organizer",
"example": "[email protected]"
}
},
"required": [
"email"
],
"additionalProperties": false
},
"timeZone": {
"description": "IANA time zone the times are written in. Datetime strings without an offset are interpreted in this zone. If omitted, offset-less datetimes are floating times (no conversion) and the poll has no time zone.",
"example": "Europe/London",
"type": "string"
},
"duration": {
"description": "Default slot length in minutes. Required when `generators` is set or an option omits its own `duration`.",
"example": 30,
"type": "integer",
"minimum": 15,
"maximum": 1440
},
"options": {
"description": "Explicit slots. Provide `options`, `generators` or both. Duplicates are removed.",
"minItems": 1,
"type": "array",
"items": {
"$ref": "#/components/schemas/TimeOptionInput"
}
},
"generators": {
"description": "Slot generators. Each expands into recurring slots from a schedule and the result is appended to `options`.",
"minItems": 1,
"type": "array",
"items": {
"$ref": "#/components/schemas/SlotGenerator"
}
}
},
"required": [
"title",
"kind"
],
"additionalProperties": false,
"title": "Time poll"
},
"TimeOptionInput": {
"type": "object",
"properties": {
"startTime": {
"type": "string",
"format": "date-time",
"description": "ISO datetime start time. A string without an offset is wall clock time in `timeZone` when that is set (`2027-03-01T09:00:00` with `timeZone: Europe/London` means 09:00 in London) and a floating time with no conversion otherwise. A string with an offset or `Z` is an absolute instant.",
"example": "2027-03-01T09:00:00"
},
"duration": {
"description": "Length of this slot in minutes. Defaults to the poll's `duration`.",
"example": 30,
"type": "integer",
"minimum": 15,
"maximum": 1440
}
},
"required": [
"startTime"
],
"additionalProperties": false,
"title": "Time option",
"description": "One time slot. The same shape `TimeOption` returns."
},
"SlotGenerator": {
"type": "object",
"properties": {
"startDate": {
"type": "string",
"format": "date",
"description": "First day of the range to generate slots on, inclusive.",
"example": "2027-03-01"
},
"endDate": {
"type": "string",
"format": "date",
"description": "Last day of the range, inclusive. The range must span fewer than 366 days.",
"example": "2027-03-05"
},
"days": {
"default": [
"mon",
"tue",
"wed",
"thu",
"fri",
"sat",
"sun"
],
"description": "Days of the week to generate slots on. Days in the range that are not listed are skipped. Defaults to every day.",
"example": [
"mon",
"tue",
"wed",
"thu",
"fri"
],
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"mon",
"tue",
"wed",
"thu",
"fri",
"sat",
"sun"
]
}
},
"from": {
"type": "string",
"pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$",
"description": "Earliest slot start on each day, as a wall clock time in `timeZone`.",
"example": "09:00"
},
"to": {
"type": "string",
"pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$",
"description": "End of the daily window, as a wall clock time in `timeZone`. A slot is only generated if it ends at or before this time.",
"example": "17:00"
},
"interval": {
"description": "Minutes between consecutive slot starts. Defaults to `duration`, which produces back to back slots.",
"example": 60,
"type": "integer",
"minimum": 15,
"maximum": 1440
}
},
"required": [
"startDate",
"endDate",
"from",
"to"
],
"additionalProperties": false,
"title": "Slot generator",
"description": "Expands into one slot of `duration` minutes every `interval` minutes between `from` and `to`, on each listed day of the week between `startDate` and `endDate`. Slots that would not end by `to` are not generated."
},
"CreatePollInput": {
"oneOf": [
{
"$ref": "#/components/schemas/CreateDatePollInput"
},
{
"$ref": "#/components/schemas/CreateTimePollInput"
}
],
"description": "`kind` chooses what participants vote on: whole days (`date`) or time slots (`time`). The request mirrors the poll the API returns: the same settings, and `options` in the same shape as the response.",
"discriminator": {
"propertyName": "kind",
"mapping": {
"date": "#/components/schemas/CreateDatePollInput",
"time": "#/components/schemas/CreateTimePollInput"
}
}
},
"ListPollsResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Poll"
}
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Cursor to fetch the next page. `null` when there are no more results.",
"example": "Xk3pQ9vLm2Ab"
}
},
"required": [
"data",
"nextCursor"
]
},
"OptionResult": {
"anyOf": [
{
"$ref": "#/components/schemas/DateOptionResult"
},
{
"$ref": "#/components/schemas/TimeOptionResult"
}
],
"description": "Results for one option. The shape follows the poll's `kind`: a `DateOptionResult` for `date` polls, a `TimeOptionResult` for `time` polls."
},
"DateOptionResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cm5h8x2k40000q9l4f7e2d3an"
},
"date": {
"type": "string",
"format": "date",
"description": "Calendar date in YYYY-MM-DD format. All-day options are floating dates with no time component and no timezone.",
"example": "2025-01-15"
},
"votes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VoteCount"
},
"description": "One entry per vote type the poll offers, in display order, always present with `count: 0` when nobody chose it."
},
"score": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Opaque ranking value: higher is better. Only comparable between options in the same response. The formula is not part of the contract and may change; do not decode it into vote counts, compare it across polls or threshold on it. Use `votes` for counts.",
"example": 5004
},
"isTopChoice": {
"type": "boolean",
"description": "Whether this option has the highest `score` in the poll. Several options share the flag when they tie. Always `false` when nobody has voted.",
"example": true
}
},
"required": [
"id",
"date",
"votes",
"score",
"isTopChoice"
],
"description": "Results for an all-day option. Only present in polls with `kind: date`."
},
"VoteCount": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/VoteType"
},
"count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Number of participants who gave this answer.",
"example": 3
}
},
"required": [
"type",
"count"
]
},
"VoteType": {
"type": "string",
"description": "A participant's answer for an option. The built-in types are `yes` (available), `ifNeedBe` (available if needed) and `no` (unavailable). New types may be added without a version change, so treat unknown values as a vote of an unfamiliar type rather than an error.",
"example": "yes"
},
"TimeOptionResult": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cm5h8x2k40000q9l4f7e2d3an"
},
"startTime": {
"type": "string",
"format": "date-time",
"description": "Start of the slot as an ISO 8601 instant in UTC.",
"example": "2025-01-15T09:00:00.000Z"
},
"duration": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Duration in minutes.",
"example": 30
},
"votes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VoteCount"
},
"description": "One entry per vote type the poll offers, in display order, always present with `count: 0` when nobody chose it."
},
"score": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Opaque ranking value: higher is better. Only comparable between options in the same response. The formula is not part of the contract and may change; do not decode it into vote counts, compare it across polls or threshold on it. Use `votes` for counts.",
"example": 5004
},
"isTopChoice": {
"type": "boolean",
"description": "Whether this option has the highest `score` in the poll. Several options share the flag when they tie. Always `false` when nobody has voted.",
"example": true
}
},
"required": [
"id",
"startTime",
"duration",
"votes",
"score",
"isTopChoice"
],
"description": "Results for a time slot. Only present in polls with `kind: time`."
},
"GetPollResultsResponse": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"pollId": {
"type": "string",
"example": "Xk3pQ9vLm2Ab"
},
"kind": {
"$ref": "#/components/schemas/PollKind"
},
"status": {
"description": "Current poll status. Polls close automatically when all options are in the past.",
"example": "open",
"$ref": "#/components/schemas/PollStatus"
},
"participantCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Total number of participants",
"example": 8
},
"options": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OptionResult"
}
},
"highScore": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The highest `score` among the options. Opaque like `score`: use it to identify the leading options, not as a measurement.",
"example": 5004
}
},
"required": [
"pollId",
"kind",
"status",
"participantCount",
"options",
"highScore"
]
}
},
"required": [
"data"
]
},
"Participant": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cm5j2r8wb0003q9l4a1x6p0zt"
},
"name": {
"type": "string",
"example": "Jane Smith"
},
"email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"example": "[email protected]"
},
"createdAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-10T12:00:00.000Z"
},
"availability": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AvailabilitySpan"
},
"description": "When the participant is available: one span per option they can make, in start order, not merged. Options they cannot make, or did not answer, are absent. Each span matches an option of the poll by its time."
}
},
"required": [
"id",
"name",
"email",
"createdAt",
"availability"
]
},
"AvailabilitySpan": {
"type": "object",
"properties": {
"start": {
"type": "string",
"format": "date-time",
"description": "Start of the span, inclusive, as a UTC instant.",
"example": "2025-01-15T09:00:00.000Z"
},
"end": {
"type": "string",
"format": "date-time",
"description": "End of the span, exclusive, as a UTC instant: a 30 minute slot starting at 09:00 ends at 09:30, and the instant 09:30 is not in it.",
"example": "2025-01-15T09:30:00.000Z"
},
"allDay": {
"type": "boolean",
"description": "True for a whole calendar day. The day is a floating date with no timezone, given as `start` at 00:00:00Z on that date and `end` at 00:00:00Z on the next; read the date from `start` and ignore the time of day.",
"example": false
},
"modifiers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Qualifiers on the availability. `ifNeedBe` means the participant can make it but would rather not. New modifiers may be added without a version change; one you do not recognise still leaves the span available.",
"example": [
"ifNeedBe"
]
}
},
"required": [
"start",
"end",
"allDay",
"modifiers"
]
},
"GetPollParticipantsResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Participant"
}
}
},
"required": [
"data"
]
},
"GetPollParticipantResponse": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Participant"
}
},
"required": [
"data"
]
},
"DeletePollResponse": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "Xk3pQ9vLm2Ab"
},
"deleted": {
"type": "boolean",
"const": true,
"example": true
}
},
"required": [
"id",
"deleted"
]
}
},
"required": [
"data"
]
}
}
},
"paths": {
"/v1/polls": {
"post": {
"operationId": "postV1Polls",
"tags": [
"Polls"
],
"summary": "Create a poll",
"description": "Creates a poll and responds with `201 Created` and the full poll, exactly as `GET /polls/:pollId` returns it. Share `inviteUrl` with participants. The request mirrors the response: `kind` chooses what participants vote on, and `options` takes the same shape the poll returns, so a poll can be recreated from the body of a `GET`. A poll has at most 100 options.\n\n## Date poll\n\nPass `kind: \"date\"` and `options`, one `{ \"date\": \"YYYY-MM-DD\" }` per day. Each becomes one all-day option. Dates are floating calendar days with no timezone, so never convert them through one. Duplicate dates are removed.\n\n```json\n{\n \"title\": \"Team offsite\",\n \"kind\": \"date\",\n \"options\": [{ \"date\": \"2027-03-01\" }, { \"date\": \"2027-03-02\" }, { \"date\": \"2027-03-03\" }]\n}\n```\n\n## Time poll\n\nPass `kind: \"time\"`, optionally a `timeZone` (an IANA zone the times are written in) and a default `duration` in minutes, and the slots as `options`, `generators` or both.\n\n### Explicit slots\n\nEach entry in `options` is one slot: a `startTime` and an optional `duration` that overrides the poll default. A `startTime` with no offset, like `2027-03-01T09:00:00`, is wall clock time in `timeZone` when that is set and a floating time with no conversion otherwise; one with an offset or `Z` is an absolute instant.\n\n```json\n{\n \"title\": \"Kickoff\",\n \"kind\": \"time\",\n \"timeZone\": \"Europe/London\",\n \"duration\": 60,\n \"options\": [\n { \"startTime\": \"2027-03-01T09:00:00\" },\n { \"startTime\": \"2027-03-02T14:00:00\", \"duration\": 90 }\n ]\n}\n```\n\n### Slot generators\n\nEach object in `generators` expands into recurring slots of `duration` minutes from a schedule, so availability across days or weeks does not have to be listed slot by slot. `duration` is required when `generators` is set.\n\n```json\n{\n \"title\": \"Interview availability\",\n \"kind\": \"time\",\n \"timeZone\": \"America/New_York\",\n \"duration\": 30,\n \"generators\": [\n {\n \"startDate\": \"2027-03-01\",\n \"endDate\": \"2027-03-05\",\n \"days\": [\"mon\", \"tue\", \"wed\", \"thu\", \"fri\"],\n \"from\": \"09:00\",\n \"to\": \"12:00\",\n \"interval\": 60\n }\n ]\n}\n```\n\nThis produces 30 minute slots at 09:00, 10:00 and 11:00 New York time on each weekday from 1 to 5 March, fifteen options in all. Drop `interval` and the window fills with back to back slots at 09:00, 09:30, 10:00, 10:30, 11:00 and 11:30.\n\n| Field | Meaning |\n| --- | --- |\n| `startDate`, `endDate` | The date range, inclusive. Fewer than 366 days. |\n| `days` | Days of the week to include: `mon` to `sun`. Optional; defaults to every day. |\n| `from` | Earliest slot start on each day, `HH:mm` in `timeZone`. |\n| `to` | End of the daily window, `HH:mm` in `timeZone`. A slot is only generated if it ends by this time. Must be later than `from`. |\n| `interval` | Minutes between slot starts. Optional; defaults to `duration`, which gives back to back slots. |\n\nA generator that cannot produce a slot is rejected with `VALIDATION_ERROR` naming the field: `to` not later than `from`, a window shorter than `duration`, or a range that contains none of the listed days. Generators are expanded when the poll is created, the result is appended to `options`, and duplicate slots are removed. A request that would exceed 100 options fails with `TOO_MANY_OPTIONS`.",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"201": {
"description": "Poll created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PollResponse"
}
}
}
},
"400": {
"description": "Invalid input",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a `WWW-Authenticate` header.",
"headers": {
"WWW-Authenticate": {
"description": "The bearer challenge, per RFC 6750.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The space associated with the API key does not have a Pro subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded. Includes a `Retry-After` header indicating how many seconds to wait before retrying.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a `Retry-After` header. Maintenance responses are sent before the rate limiter runs and carry no `RateLimit-*` headers.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePollInput"
},
"examples": {
"Date poll": {
"summary": "Date poll (all-day options)",
"description": "Let participants pick between calendar days. Each option is one all-day date.",
"value": {
"title": "Team offsite",
"kind": "date",
"description": "Which days work for a two day offsite?",
"options": [
{
"date": "2027-03-01"
},
{
"date": "2027-03-02"
},
{
"date": "2027-03-03"
}
]
}
},
"Time poll with explicit slots": {
"summary": "Time poll (explicit slots)",
"description": "Offer specific time slots. Datetimes without an offset are wall clock times in `timeZone`; this example offers 09:00 and 14:00 in London. Append `Z` or an offset for an absolute instant instead. A slot may override the poll's `duration`.",
"value": {
"title": "Project kickoff",
"kind": "time",
"location": "Zoom",
"timeZone": "Europe/London",
"duration": 60,
"options": [
{
"startTime": "2027-03-01T09:00:00"
},
{
"startTime": "2027-03-01T14:00:00",
"duration": 90
}
]
}
},
"Time poll with a slot generator": {
"summary": "Time poll (slot generator)",
"description": "Expand recurring slots across a date range. This example generates 30 minute slots at 09:00, 10:00 and 11:00 (New York time) every weekday from 1 to 5 March.",
"value": {
"title": "Interview availability",
"kind": "time",
"timeZone": "America/New_York",
"duration": 30,
"generators": [
{
"startDate": "2027-03-01",
"endDate": "2027-03-05",
"days": [
"mon",
"tue",
"wed",
"thu",
"fri"
],
"from": "09:00",
"to": "12:00",
"interval": 60
}
]
}
},
"Time poll mixing slots and a generator": {
"summary": "Time poll (explicit slots + generator)",
"description": "`options` and `generators` combine. When `interval` is omitted it defaults to `duration`, so this generator produces back to back 90 minute slots at 14:00 and 15:30 on Monday and Wednesday.",
"value": {
"title": "Product workshop",
"kind": "time",
"timeZone": "Europe/Berlin",
"duration": 90,
"options": [
{
"startTime": "2027-03-06T10:00:00"
}
],
"generators": [
{
"startDate": "2027-03-08",
"endDate": "2027-03-10",
"days": [
"mon",
"wed"
],
"from": "14:00",
"to": "17:00"
}
]
}
}
}
}
}
}
},
"get": {
"operationId": "getV1Polls",
"tags": [
"Polls"
],
"summary": "List polls",
"description": "Lists the polls in the space associated with the API key, sorted by creation date (newest first).\n\nUse the `status` query parameter to only return polls in a given state — for example `status=open` to sweep polls that are still collecting responses. Results are paginated with a cursor: pass the `nextCursor` value from the previous response to fetch the next page.",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListPollsResponse"
}
}
}
},
"400": {
"description": "Invalid query parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a `WWW-Authenticate` header.",
"headers": {
"WWW-Authenticate": {
"description": "The bearer challenge, per RFC 6750.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The space associated with the API key does not have a Pro subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded. Includes a `Retry-After` header indicating how many seconds to wait before retrying.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a `Retry-After` header. Maintenance responses are sent before the rate limiter runs and carry no `RateLimit-*` headers.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"parameters": [
{
"in": "query",
"name": "status",
"schema": {
"example": "open",
"$ref": "#/components/schemas/PollStatus"
},
"description": "Filter polls by status. Omit to include all statuses."
},
{
"in": "query",
"name": "cursor",
"schema": {
"example": "Xk3pQ9vLm2Ab",
"type": "string"
},
"description": "Cursor for pagination. Pass the `nextCursor` value from the previous response to fetch the next page."
},
{
"in": "query",
"name": "limit",
"schema": {
"default": 20,
"example": 20,
"type": "integer",
"minimum": 1,
"maximum": 100
},
"description": "Number of polls to return per page (1-100)."
}
]
}
},
"/v1/polls/{pollId}": {
"get": {
"operationId": "getV1PollsByPollId",
"tags": [
"Polls"
],
"summary": "Get a poll",
"description": "Retrieves a poll by ID with its options, settings, organizer and `participantCount`. The poll must belong to the space associated with the API key. Compare `updatedAt` between reads to notice changes.",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PollResponse"
}
}
}
},
"401": {
"description": "The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a `WWW-Authenticate` header.",
"headers": {
"WWW-Authenticate": {
"description": "The bearer challenge, per RFC 6750.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The space associated with the API key does not have a Pro subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Poll not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded. Includes a `Retry-After` header indicating how many seconds to wait before retrying.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a `Retry-After` header. Maintenance responses are sent before the rate limiter runs and carry no `RateLimit-*` headers.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"parameters": [
{
"schema": {
"type": "string"
},
"in": "path",
"name": "pollId",
"required": true
}
]
},
"delete": {
"operationId": "deleteV1PollsByPollId",
"tags": [
"Polls"
],
"summary": "Delete a poll",
"description": "Deletes a poll by ID. The poll must belong to the space associated with the API key.",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Poll deleted successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeletePollResponse"
}
}
}
},
"401": {
"description": "The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a `WWW-Authenticate` header.",
"headers": {
"WWW-Authenticate": {
"description": "The bearer challenge, per RFC 6750.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The space associated with the API key does not have a Pro subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Poll not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded. Includes a `Retry-After` header indicating how many seconds to wait before retrying.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a `Retry-After` header. Maintenance responses are sent before the rate limiter runs and carry no `RateLimit-*` headers.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"parameters": [
{
"schema": {
"type": "string"
},
"in": "path",
"name": "pollId",
"required": true
}
]
}
},
"/v1/polls/{pollId}/results": {
"get": {
"operationId": "getV1PollsByPollIdResults",
"tags": [
"Polls"
],
"summary": "Get poll results",
"description": "Retrieves aggregated voting results for a poll: vote counts per option without individual participant data. Use `GET /polls/:pollId/participants` to list who responded.\n\n`votes` lists every vote type the poll offers with its count, zero included. `score` is an opaque ranking value: sort by it to order options from best to worst, and use `isTopChoice` or `highScore` to find the leading options. Its formula is not part of the contract, so do not decode it, compare it across polls or threshold on it.",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetPollResultsResponse"
}
}
}
},
"401": {
"description": "The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a `WWW-Authenticate` header.",
"headers": {
"WWW-Authenticate": {
"description": "The bearer challenge, per RFC 6750.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The space associated with the API key does not have a Pro subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Poll not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded. Includes a `Retry-After` header indicating how many seconds to wait before retrying.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a `Retry-After` header. Maintenance responses are sent before the rate limiter runs and carry no `RateLimit-*` headers.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"parameters": [
{
"schema": {
"type": "string"
},
"in": "path",
"name": "pollId",
"required": true
}
]
}
},
"/v1/polls/{pollId}/participants": {
"get": {
"operationId": "getV1PollsByPollIdParticipants",
"tags": [
"Polls"
],
"summary": "List poll participants",
"description": "Lists every participant of a poll in one response, oldest response first, each with their availability. The poll must belong to the space associated with the API key.\n\nFor aggregate counts per option use the results endpoint.",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetPollParticipantsResponse"
}
}
}
},
"401": {
"description": "The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a `WWW-Authenticate` header.",
"headers": {
"WWW-Authenticate": {
"description": "The bearer challenge, per RFC 6750.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The space associated with the API key does not have a Pro subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Poll not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded. Includes a `Retry-After` header indicating how many seconds to wait before retrying.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a `Retry-After` header. Maintenance responses are sent before the rate limiter runs and carry no `RateLimit-*` headers.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"parameters": [
{
"schema": {
"type": "string"
},
"in": "path",
"name": "pollId",
"required": true
}
]
}
},
"/v1/polls/{pollId}/participants/{participantId}": {
"get": {
"operationId": "getV1PollsByPollIdParticipantsByParticipantId",
"tags": [
"Polls"
],
"summary": "Get a poll participant",
"description": "Returns one participant of a poll with their availability. The poll must belong to the space associated with the API key. This is the endpoint to call from a `poll.participant.*` webhook.",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetPollParticipantResponse"
}
}
}
},
"401": {
"description": "The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a `WWW-Authenticate` header.",
"headers": {
"WWW-Authenticate": {
"description": "The bearer challenge, per RFC 6750.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "The space associated with the API key does not have a Pro subscription",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Poll not found (`POLL_NOT_FOUND`) or participant not found (`PARTICIPANT_NOT_FOUND`)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded. Includes a `Retry-After` header indicating how many seconds to wait before retrying.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"503": {
"description": "The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a `Retry-After` header. Maintenance responses are sent before the rate limiter runs and carry no `RateLimit-*` headers.",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying the request.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"parameters": [
{
"schema": {
"type": "string"
},
"in": "path",
"name": "pollId",
"required": true
},
{
"schema": {
"type": "string"
},
"in": "path",
"name": "participantId",
"required": true
}
]
}
}
}
}