> ## 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.

# Update a poll or change its status

> Send only the fields to change, or a new status. An invalid status transition answers 400.



## OpenAPI

````yaml /experiences/api-reference/experiences.openapi.yaml patch /polls/{poll_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:
  /polls/{poll_id}:
    parameters:
      - name: poll_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/PollId'
    patch:
      tags:
        - Poll API
      summary: Update a poll or change its status
      description: >-
        Send only the fields to change, or a new status. An invalid status
        transition answers 400.
      operationId: updatePoll
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PollPatch'
            examples:
              make-live:
                summary: Make it live
                value:
                  status: live
              hide:
                summary: Hide it from fans
                value:
                  status: hidden
              retire:
                summary: Retire it
                value:
                  status: deleted
              edit-options:
                summary: Edit the options
                description: >-
                  Send every existing option's id back; a new option has none,
                  and gets one.
                value:
                  options:
                    - id: opt_01M7WQND9RKTH6WF72R2VFKZ1S
                      label: Jordan Mensah
                    - id: opt_01M7WQNDD71FCAQ370M9XTD2GA
                      label: Kai Brennan
                    - label: Theo Marsh
      responses:
        '200':
          description: The item, as saved.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Poll'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  schemas:
    PollId:
      type: string
      pattern: ^pol_[0-9A-HJKMNP-TV-Z]{26}$
      examples:
        - pol_01JBX7Q3A1B2C3D4E5F6G7H8J9
    PollPatch:
      type: object
      minProperties: 1
      additionalProperties: false
      description: >-
        The fields to change. A list such as options, if sent, replaces the
        whole list. status changes its status: an invalid transition answers
        400.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
          description: The item's name, as the hub card and on-air graphics show it.
        starts_at:
          $ref: '#/components/schemas/Timestamp'
          description: Optional. It opens then (status scheduled until it does).
        ends_at:
          $ref: '#/components/schemas/Timestamp'
          description: Optional. It closes then.
        metadata:
          $ref: '#/components/schemas/Metadata'
        status:
          $ref: '#/components/schemas/Status'
        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.
        requires_sign_in:
          type: boolean
          description: >-
            True if only signed-in fans may vote or post. If you leave it out,
            your account's setting.
        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
          minItems: 1
          maxItems: 10
          items:
            $ref: '#/components/schemas/TextOption'
    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'
    Timestamp:
      type: string
      format: date-time
      description: RFC 3339, in UTC.
    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.
    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
    TextOption:
      type: object
      required:
        - label
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/OptionId'
          description: >
            Leave it out only for a new option, and one is minted. On an edit,
            send each existing option's id back; an id this

            item doesn't have answers 400 (unknown-option). A removed option's
            ID is never reused.
        label:
          type: string
          minLength: 1
          maxLength: 200
    ExperienceId:
      type: string
      pattern: ^exp_[0-9A-HJKMNP-TV-Z]{26}$
      examples:
        - exp_01JBX7Q2T8M4K9R6V3N5P0WZCD
    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.
    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
  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
  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'
    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'
    Unavailable:
      description: Writes can't be taken right now. 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.