> ## Documentation Index > Fetch the complete documentation index at: https://developer.dizplai.com/llms.txt > Use this file to discover all available pages before exploring further. # List polls ## OpenAPI ````yaml /experiences/api-reference/experiences.openapi.yaml get /polls openapi: 3.1.0 info: title: 'Dizplai API: Experiences' version: 0.1.0 summary: Create, run and read experiences with their polls, and send fans' votes. description: > Experiences and their polls on the Dizplai API at `api.dizplai.com`. Reads are kept current within seconds of a change, and lists return live items unless you ask for other statuses. **Headers.** Every request sends `x-api-key`: a platform's secret key, from servers only, or an app's publishable key (`pk_live_...`). A platform's servers also send `Authorization: Bearer` with a short-lived issuer token. A fan app adds the fan's token in `Authorization` on votes. **Conventions.** snake_case; `after` and `limit` paging (50 by default, 100 at most) with `{items, next}`; RFC 9457 problems with `request_id`, and `x-request-id` on every response; an `Idempotency-Key` on creates, honoured for 24 hours. Draft 0.1.0, for review. contact: name: Dizplai servers: - url: https://api.dizplai.com/v1 description: The Dizplai API. security: - apiKey: [] platformToken: [] tags: - name: Experiences description: Create, update and retire experiences, and read them with their items. - name: Poll API description: >- Fans vote once from a short list of options. The crowd's answer is the point. paths: /polls: get: tags: - Poll API summary: List polls operationId: listPolls parameters: - $ref: '#/components/parameters/StatusFilter' - $ref: '#/components/parameters/ExperienceIdFilter' - $ref: '#/components/parameters/MetadataFilter' - $ref: '#/components/parameters/After' - $ref: '#/components/parameters/Limit' responses: '200': description: A page of items, each with type poll. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/PollPage' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorised' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' security: - apiKey: [] platformToken: [] - apiKey: [] components: parameters: StatusFilter: name: status in: query required: false schema: type: string description: >- A comma list of statuses, such as live,closed. Only live ones by default. On experiences, it filters the items inside them too. ExperienceIdFilter: name: experience_id in: query required: false schema: $ref: '#/components/schemas/ExperienceId' description: Only items in this experience. MetadataFilter: name: metadata in: query required: false style: deepObject explode: true schema: type: object additionalProperties: type: string description: >- Exact match on metadata keys, such as metadata[event_id]=ev_2041. Several keys AND together. After: name: after in: query required: false schema: type: string description: The next value from the previous page. Limit: name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 50 headers: RequestId: description: The request's ID. Quote it to support. schema: type: string RetryAfter: description: Seconds to wait before retrying. schema: type: integer minimum: 0 schemas: PollPage: type: object required: - items - next properties: items: type: array items: $ref: '#/components/schemas/Poll' next: type: - string - 'null' ExperienceId: type: string pattern: ^exp_[0-9A-HJKMNP-TV-Z]{26}$ examples: - exp_01JBX7Q2T8M4K9R6V3N5P0WZCD Poll: type: object description: Poll, results included. required: - id - name - experience_id - status - starts_at - ends_at - metadata - api_version - created_at - updated_at - type - question - options - results_visibility - total_votes - final - requires_sign_in properties: id: $ref: '#/components/schemas/PollId' name: type: - string - 'null' experience_id: $ref: '#/components/schemas/ExperienceId' status: $ref: '#/components/schemas/Status' starts_at: type: - string - 'null' format: date-time description: When it opens. Null when it opens on demand. ends_at: type: - string - 'null' format: date-time description: When it closes. Null otherwise. metadata: $ref: '#/components/schemas/Metadata' api_version: type: integer minimum: 1 readOnly: true description: >- The major version of the widget type's own API, kept for the item's life. created_at: $ref: '#/components/schemas/Timestamp' updated_at: $ref: '#/components/schemas/Timestamp' type: const: poll results_visibility: type: string enum: - live - after_vote - after_close - hidden default: after_vote description: >- When fans may see results: live, after_vote, after_close (once votes have stopped) or hidden. Platform reads always include them; fan app reads hold them back until the item closes, unless live. total_votes: type: - integer - 'null' minimum: 0 description: Fans who voted. Null until the first result. final: type: boolean description: >- True once votes have stopped and been recounted: the official result. requires_sign_in: type: boolean question: type: string minLength: 1 maxLength: 300 description: The question fans answer. subtitle: type: string maxLength: 300 description: Supporting text under the question. options: type: array items: type: object required: - id - label - votes - percent properties: id: $ref: '#/components/schemas/OptionId' label: type: string minLength: 1 maxLength: 200 votes: $ref: '#/components/schemas/Votes' percent: $ref: '#/components/schemas/Percent' Problem: type: object required: - type - title - status - request_id description: An RFC 9457 problem, as in the Dizplai API. Quote request_id to support. properties: type: type: string format: uri-reference description: >- Stable per kind of error, such as https://api.dizplai.com/problems/invalid-status, https://api.dizplai.com/problems/unknown-option for an option id the item doesn't have, or https://api.dizplai.com/problems/invalid-fan-token for a missing, invalid or expired fan token on a vote. title: type: string status: type: integer minimum: 400 maximum: 599 detail: type: string request_id: type: string description: Matches the x-request-id response header. errors: type: array description: Field-level validation errors. items: type: object required: - pointer - message properties: pointer: type: string description: A JSON Pointer to the field. message: type: string PollId: type: string pattern: ^pol_[0-9A-HJKMNP-TV-Z]{26}$ examples: - pol_01JBX7Q3A1B2C3D4E5F6G7H8J9 Status: type: string description: > The item's status: values are added, never removed. scheduled: waits for starts_at, then goes live. live: taking votes. hidden: not shown to fans; the state underneath is kept, so making it live or closed again restores it. closed: votes have stopped. deleted: retired; reads still return it, with this status. enum: - scheduled - live - hidden - closed - deleted Metadata: type: object maxProperties: 50 propertyNames: maxLength: 40 additionalProperties: type: string maxLength: 500 description: > Free-form tags: up to 50 keys of up to 40 characters, values up to 500. One reserved key, event_id: the event the item is about. Every other key is yours, and never interpreted. properties: event_id: type: string maxLength: 64 description: The event the item is about. Reserved. Timestamp: type: string format: date-time description: RFC 3339, in UTC. OptionId: type: string description: >- An option in a poll, what a fan picks. Minted when the option is created, opaque, and never reused, even after the option is removed. pattern: ^opt_[0-9A-HJKMNP-TV-Z]{26}$ examples: - opt_01M7WQND9RKTH6WF72R2VFKZ1S Votes: type: - integer - 'null' minimum: 0 description: Null until the first result. Percent: type: - number - 'null' minimum: 0 maximum: 100 description: Of fans who voted, 0 to 100, rounded to one decimal place. responses: BadRequest: description: >- The body or a parameter is invalid, a status value is unknown, the status transition isn't allowed, or an option or question id isn't one this item has (unknown-option, unknown-question). headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Unauthorised: description: >- A missing or invalid API key, or a missing, invalid or expired issuer token. Refresh the token and retry once. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Forbidden: description: >- Not allowed for this caller, or this client doesn't have this widget type. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' TooManyRequests: description: Over the limit. Retry after Retry-After seconds. headers: x-request-id: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: >- Which app is calling, and its usage plan: a platform's secret key, from servers only, or an app's publishable key (pk_live_...), safe in app code. It identifies the app and grants nothing on its own. platformToken: type: http scheme: bearer bearerFormat: JWT description: A platform's short-lived issuer token, for the same client as the key. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.