> ## 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 collections > Lists your live collections, such as one for each match or show, to build your screens from. An offline collection isn't listed. ## OpenAPI ````yaml /experiences/api-reference/experiences.openapi.yaml get /collections openapi: 3.1.0 info: title: 'Dizplai API: Experiences' version: 1.0.0 summary: Read polls, Fan Voices and collections, and let fans vote and send messages. description: > Show polls and Fan Voices in your own apps and sites, and let fans take part: read experiences and collections, send fans' votes and messages, and read back a fan's own vote and messages. **Headers.** Send `x-api-key`, your organisation's API key, on every request. When a fan takes part, or reads their own vote or messages, add their token from your own login as `Authorization: Bearer `. **Names.** An experience is one thing fans take part in: a poll or a Fan Voice. A collection groups experiences for a match or show, and an experience can be in many collections. Every ID is a UUID: store it in a UUID column or as text, and never parse it. **Conventions.** snake_case fields; `after` and `limit` paging (50 by default, 100 at most) with `{items, next}`; errors are RFC 9457 problems with a stable `code` and a `request_id`, and every response carries `x-request-id`. Types, statuses and codes can gain values within v1, so ignore one you don't know. **Refreshing.** Read an open poll every 10 seconds and lists every 30 seconds, and wait as long as `Retry-After` says after a `429` or `503`. The Experiences guide has the details. contact: name: Dizplai servers: - url: https://api.dizplai.com/v1 description: The Dizplai API. security: - apiKey: [] tags: - name: Experiences description: >- Everything fans can take part in, in one list: build a match or show screen from it, drawing each experience by its type. - name: Collections description: >- Groups of experiences, one for each match or show, to organise your screens. An experience can be in many collections, in its own order in each. - name: Polls description: >- A poll asks fans one question with a short list of answers. Read polls and their results, send a fan's vote, and read back the vote they made. - name: Fan Voices description: >- A Fan Voice asks fans to reply in their own words, with text, a voice note or a photo. Read a Fan Voice, send a fan's message, and show the fan what happened to it. Fans never see each other's messages. paths: /collections: get: tags: - Collections summary: List collections description: >- Lists your live collections, such as one for each match or show, to build your screens from. An offline collection isn't listed. operationId: listCollections parameters: - $ref: '#/components/parameters/MetadataFilter' - $ref: '#/components/parameters/After' - $ref: '#/components/parameters/Limit' responses: '200': description: >- A page of collections, newest first. To list a collection's experiences, filter List experiences by its collection_id. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/CollectionPage' examples: example: $ref: '#/components/examples/CollectionPage' empty: $ref: '#/components/examples/EmptyPage' '400': $ref: '#/components/responses/ListBadRequest' '401': $ref: '#/components/responses/Unauthorised' '403': $ref: '#/components/responses/ReadForbidden' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ReadUnavailable' components: parameters: MetadataFilter: name: metadata in: query required: false style: deepObject explode: true schema: type: object properties: event_id: type: string description: Only those for this match or show. description: >- Filter by tags, such as `metadata[event_id]=ev_2041` for one match or show. Any other tag key works the same way. An exact match; with several keys, all must match. After: name: after in: query required: false schema: type: string description: >- Where the next page starts, the next value from the previous page. Leave it out for the first page. Limit: name: limit in: query required: false description: How many items a page holds, 1 to 100. 50 by default. 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: >- How long to wait before retrying, as a whole number of seconds. Sent with every 429 and 503. schema: type: integer minimum: 0 schemas: CollectionPage: type: object required: - items - next properties: items: type: array description: Collections, newest created first. items: $ref: '#/components/schemas/Collection' next: type: - string - 'null' description: Pass as after for the next page. Null on the last page. Collection: type: object description: >- A group of experiences for one match or show, to build a screen from. An experience can be in many collections, in its own order in each. Get a collection adds its experiences when asked with include=experiences (CollectionWithExperiences); List collections never does. required: - id - name - status - starts_at - ends_at - metadata - locale - created_at - updated_at properties: id: $ref: '#/components/schemas/CollectionId' name: type: string description: The collection's name, such as the match, for a screen's heading. status: $ref: '#/components/schemas/CollectionStatus' starts_at: type: - string - 'null' format: date-time description: >- The match or show's start time, for display. It doesn't open any experience. ends_at: type: - string - 'null' format: date-time description: >- The match or show's end time, for display. It doesn't close any experience. metadata: $ref: '#/components/schemas/Metadata' locale: $ref: '#/components/schemas/Locale' description: The language the collection's text is written in, such as en-GB. created_at: $ref: '#/components/schemas/Timestamp' description: When the collection was created. updated_at: $ref: '#/components/schemas/Timestamp' description: When the collection last changed. Problem: type: object required: - type - code - title - status - request_id description: >- What went wrong, in the same shape for every error: an RFC 9457 problem with a stable code. Act on code, which never changes meaning within a version, and on the HTTP status for a code you don't know. Quote request_id to support. properties: type: type: string format: uri-reference description: >- One URL per code: https://api.dizplai.com/problems/ followed by the code with hyphens, such as https://api.dizplai.com/problems/unknown-option for unknown_option. code: type: string x-extensible-enum: - invalid_request - unknown_option - not_open - media_not_accepted - invalid_upload - invalid_api_key - invalid_fan_token - forbidden - fan_blocked - sign_in_required - message_limit_reached - not_found - idempotency_conflict - rate_limited - unavailable description: > More codes may be added: for one you don't know, act on the HTTP status. | code | Status | Retry? | Meaning | |---|---|---|---| | invalid_request | 400 | No | The body or a parameter is invalid, or a required header such as Idempotency-Key is missing. | | unknown_option | 400 | No; read the poll again | An option ID the poll doesn't have. | | not_open | 400 | No; read the experience again | The experience isn't taking votes or messages: it isn't live yet, or votes have stopped. | | media_not_accepted | 400 | No | The Fan Voice doesn't take this kind of message, or the file's type or size is outside the limits. | | invalid_upload | 400 | No; upload again | The upload_id is unknown, already used or another fan's, or the file was never uploaded or its type or size differs from what you asked for. | | invalid_api_key | 401 | No | A missing or invalid x-api-key. | | invalid_fan_token | 401 | Once, with a fresh token | A missing, invalid or expired fan token, or one from another organisation's login. It carries WWW-Authenticate. | | forbidden | 403 | No | Your API key isn't allowed to make this request. | | fan_blocked | 403 | No | The fan is blocked from this Fan Voice. | | sign_in_required | 403 | No; ask the fan to sign in | A guest on an experience that needs a signed-in fan, or a guest's voice note or photo. | | message_limit_reached | 403 | No | The fan has used up this Fan Voice's messages of this kind. | | not_found | 404 | No | Not found, or not yours. | | idempotency_conflict | 409 | No | An Idempotency-Key reused with a different body while it's kept: 24 hours, or 5 minutes for an upload. | | rate_limited | 429 | After Retry-After | Too many requests. | | unavailable | 503 | After Retry-After | Votes or messages can't be taken right now. | title: type: string description: A short title for the code, such as Not open. It doesn't change. status: type: integer description: The HTTP status code. minimum: 400 maximum: 599 detail: type: string description: >- What went wrong, in plain English. It can change, so don't act on it. request_id: type: string description: Matches the x-request-id response header. errors: type: array description: Field-level validation errors, with invalid_request. items: type: object required: - pointer - message properties: pointer: type: string description: A JSON Pointer to the field. message: type: string description: What's wrong with that field. CollectionId: type: string description: A collection's ID, a UUID. format: uuid examples: - 0192fa7b-8b48-768f-90d1-d3ed6f427962 CollectionStatus: type: string x-extensible-enum: - offline - live description: >- Whether fans can see the collection. offline: not listed, and getting it answers 404. live: listed and shown. Its experiences keep their own status. More statuses may be added: treat one you don't know as offline. Metadata: type: object maxProperties: 50 propertyNames: maxLength: 40 additionalProperties: type: string maxLength: 500 description: >- Tags for finding and grouping things, such as the match or show they're about. Filter lists by them with `metadata[key]=value`. Up to 50 keys of up to 40 characters, values up to 500. One key is reserved, event_id, set by your producers; every other key is yours, and never interpreted. properties: event_id: type: string maxLength: 64 description: >- An ID for the match or show this is about, set by your producers. Reserved. Locale: type: string maxLength: 35 pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$ examples: - en-GB description: >- A BCP 47 language tag. en-GB, British English, is the only language for now. More may be added: show text in a locale you don't know as it is. x-extensible-enum: - en-GB Timestamp: type: string format: date-time description: A date and time, RFC 3339, in UTC. examples: CollectionPage: value: items: - id: 0192fa7b-8b48-768f-90d1-d3ed6f427962 name: Hartley Town v Riverside status: live starts_at: '2026-11-21T19:45:00Z' ends_at: null metadata: event_id: ev_2041 round: QF locale: en-GB created_at: '2026-11-20T15:02:11Z' updated_at: '2026-11-21T20:41:07Z' - id: 0192fa7b-ac4c-7541-ac74-700ad0f93718 name: Player of the season status: live starts_at: null ends_at: null metadata: {} locale: en-GB created_at: '2026-11-20T15:02:11Z' updated_at: '2026-11-21T20:41:07Z' next: null EmptyPage: summary: Nothing to show value: items: [] next: null responses: ListBadRequest: description: A query parameter is invalid (invalid_request). headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: invalid_request: summary: invalid_request value: type: https://api.dizplai.com/problems/invalid-request code: invalid_request title: Invalid request status: 400 detail: limit must be between 1 and 100. request_id: 01JBX8P2R4T6V8X0Z2B4D6F8H0 Unauthorised: description: >- A missing or invalid x-api-key (invalid_api_key). Don't retry: check the key. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: invalid_api_key: summary: invalid_api_key value: type: https://api.dizplai.com/problems/invalid-api-key code: invalid_api_key title: Invalid API key status: 401 detail: The x-api-key isn't recognised. request_id: 01JBX8P2R4T6V8X0Z2B4D6F8H0 ReadForbidden: description: >- Not allowed for this caller or origin (forbidden), such as a browser Origin your organisation hasn't registered, or a platform key sent from a browser. Retrying won't help: check the key and your registered origins. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: forbidden: summary: forbidden value: type: https://api.dizplai.com/problems/forbidden code: forbidden title: Forbidden status: 403 detail: This origin isn't registered for this organisation. request_id: 01JBX8P2R4T6V8X0Z2B4D6F8H0 TooManyRequests: description: >- Too many requests (rate_limited). Wait the number of seconds in Retry-After, then retry. headers: x-request-id: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: rate_limited: summary: rate_limited value: type: https://api.dizplai.com/problems/rate-limited code: rate_limited title: Rate limited status: 429 detail: Too many requests. Retry after 2 seconds. request_id: 01JBX8P2R4T6V8X0Z2B4D6F8H0 ReadUnavailable: description: >- This can't be read right now (unavailable). Wait the number of seconds in Retry-After, then retry, and keep showing what you last read. headers: x-request-id: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: unavailable: summary: unavailable value: type: https://api.dizplai.com/problems/unavailable code: unavailable title: Unavailable status: 503 detail: This can't be read right now. Retry after 5 seconds. request_id: 01JBX8P2R4T6V8X0Z2B4D6F8H0 securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: >- Your organisation's API key, supplied by Dizplai. Send it on every request. It isn't a secret, so it can ship in your app: what a fan does is protected by the fan's token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.