> ## 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. # Get one experience ## OpenAPI ````yaml /experiences/api-reference/experiences.openapi.yaml get /experiences/{experience_id} 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: /experiences/{experience_id}: parameters: - $ref: '#/components/parameters/ExperienceIdPath' get: tags: - Experiences summary: Get one experience operationId: getExperience parameters: - $ref: '#/components/parameters/ItemStatusFilter' responses: '200': description: The experience, any status including deleted. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Experience' examples: example: $ref: '#/components/examples/Experience' '401': $ref: '#/components/responses/Unauthorised' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' security: - apiKey: [] platformToken: [] - apiKey: [] components: parameters: ExperienceIdPath: name: experience_id in: path required: true schema: $ref: '#/components/schemas/ExperienceId' ItemStatusFilter: name: status in: query required: false schema: type: string description: Filters the items returned. Every status but deleted by default. 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: Experience: type: object required: - id - name - status - qr_image_url - starts_at - ends_at - metadata - locale - items - created_at - updated_at properties: id: $ref: '#/components/schemas/ExperienceId' name: type: string status: $ref: '#/components/schemas/Status' description: >- Worked out from its items: live if any item is, else hidden, else closed. qr_image_url: type: - string - 'null' format: uri description: The experience's QR code. starts_at: type: - string - 'null' format: date-time ends_at: type: - string - 'null' format: date-time metadata: $ref: '#/components/schemas/Metadata' locale: type: string hub_id: $ref: '#/components/schemas/HubId' items: type: array description: Every item, types mixed, in display order, results included. items: $ref: '#/components/schemas/AnyItem' created_at: $ref: '#/components/schemas/Timestamp' updated_at: $ref: '#/components/schemas/Timestamp' ExperienceId: type: string pattern: ^exp_[0-9A-HJKMNP-TV-Z]{26}$ examples: - exp_01JBX7Q2T8M4K9R6V3N5P0WZCD 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. HubId: type: string description: > A hub in a creator network: one creator's fan site, registered under the network's client ID. Present only in creator networks; a client without a network has no hub ID. pattern: ^hub_[0-9A-HJKMNP-TV-Z]{26}$ AnyItem: description: An item of any type, shaped by its type. Skip types you don't know. oneOf: - $ref: '#/components/schemas/Poll' Timestamp: type: string format: date-time description: RFC 3339, in UTC. 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 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' PollId: type: string pattern: ^pol_[0-9A-HJKMNP-TV-Z]{26}$ examples: - pol_01JBX7Q3A1B2C3D4E5F6G7H8J9 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. examples: Experience: value: id: exp_01JBX7Q2T8M4K9R6V3N5P0WZCD name: Hartley Town v Riverside status: live qr_image_url: null starts_at: '2026-11-21T19:45:00Z' ends_at: null metadata: event_id: ev_2041 round: QF locale: en-GB items: - id: pol_01JBX7Q3A1B2C3D4E5F6G7H8J9 type: poll name: Player of the match experience_id: exp_01JBX7Q2T8M4K9R6V3N5P0WZCD status: live starts_at: null ends_at: null metadata: event_id: ev_2041 api_version: 1 created_at: '2026-11-20T15:02:11Z' updated_at: '2026-11-21T20:41:07Z' results_visibility: after_vote requires_sign_in: false question: Who was your player of the match? options: - id: opt_01M7WQND9RKTH6WF72R2VFKZ1S label: Jordan Mensah votes: 2105 percent: 50 - id: opt_01M7WQNDD71FCAQ370M9XTD2GA label: Kai Brennan votes: 1263 percent: 30 - id: opt_01M7WQNDECMSCTEM2HRAJT61R8 label: Amara Osei votes: 842 percent: 20 total_votes: 4210 final: false created_at: '2026-11-20T15:02:11Z' updated_at: '2026-11-21T20:41:07Z' responses: 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' NotFound: description: Not found, or another client's. 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.