swagger: '2.0'
info:
  title: Votes API
  description: Endpoints for polls, options, and votes.
  version: v1
host: eboard.devsgraphics.com
schemes:
- https
basePath: /api/votes
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  Basic:
    type: basic
security:
- Basic: []
paths:
  /options/:
    get:
      operationId: options_list
      summary: Manage options belonging to polls.
      description: |-
        - Filter by `?poll=<poll_uuid>`
        - Search by text, description, or poll title.
        - Create/update expects `poll_id` in the payload.
      parameters:
      - name: search
        in: query
        description: A search term.
        required: false
        type: string
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        type: string
      - name: page
        in: query
        description: A page number within the paginated result set.
        required: false
        type: integer
      - name: page_size
        in: query
        description: Number of results to return per page.
        required: false
        type: integer
      responses:
        '200':
          description: ''
          schema:
            required:
            - count
            - results
            type: object
            properties:
              count:
                type: integer
              next:
                type: string
                format: uri
                x-nullable: true
              previous:
                type: string
                format: uri
                x-nullable: true
              results:
                type: array
                items:
                  $ref: '#/definitions/PollOption'
      tags:
      - options
    post:
      operationId: options_create
      summary: Manage options belonging to polls.
      description: |-
        - Filter by `?poll=<poll_uuid>`
        - Search by text, description, or poll title.
        - Create/update expects `poll_id` in the payload.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/PollOption'
      responses:
        '201':
          description: ''
          schema:
            $ref: '#/definitions/PollOption'
      tags:
      - options
    parameters: []
  /options/{id}/:
    get:
      operationId: options_read
      summary: Manage options belonging to polls.
      description: |-
        - Filter by `?poll=<poll_uuid>`
        - Search by text, description, or poll title.
        - Create/update expects `poll_id` in the payload.
      parameters: []
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/PollOption'
      tags:
      - options
    put:
      operationId: options_update
      summary: Manage options belonging to polls.
      description: |-
        - Filter by `?poll=<poll_uuid>`
        - Search by text, description, or poll title.
        - Create/update expects `poll_id` in the payload.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/PollOption'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/PollOption'
      tags:
      - options
    patch:
      operationId: options_partial_update
      summary: Manage options belonging to polls.
      description: |-
        - Filter by `?poll=<poll_uuid>`
        - Search by text, description, or poll title.
        - Create/update expects `poll_id` in the payload.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/PollOption'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/PollOption'
      tags:
      - options
    delete:
      operationId: options_delete
      summary: Manage options belonging to polls.
      description: |-
        - Filter by `?poll=<poll_uuid>`
        - Search by text, description, or poll title.
        - Create/update expects `poll_id` in the payload.
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - options
    parameters:
    - name: id
      in: path
      description: A UUID string identifying this Poll Option.
      required: true
      type: string
      format: uuid
  /polls/:
    get:
      operationId: polls_list
      description: ''
      parameters:
      - name: search
        in: query
        description: A search term.
        required: false
        type: string
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        type: string
      - name: page
        in: query
        description: A page number within the paginated result set.
        required: false
        type: integer
      - name: page_size
        in: query
        description: Number of results to return per page.
        required: false
        type: integer
      responses:
        '200':
          description: ''
          schema:
            required:
            - count
            - results
            type: object
            properties:
              count:
                type: integer
              next:
                type: string
                format: uri
                x-nullable: true
              previous:
                type: string
                format: uri
                x-nullable: true
              results:
                type: array
                items:
                  $ref: '#/definitions/PollSummary'
      tags:
      - polls
    post:
      operationId: polls_create
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/PollCreateUpdate'
      responses:
        '201':
          description: ''
          schema:
            $ref: '#/definitions/PollCreateUpdate'
      tags:
      - polls
    parameters: []
  /polls/{id}/:
    get:
      operationId: polls_read
      description: ''
      parameters: []
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/PollDetail'
      tags:
      - polls
    put:
      operationId: polls_update
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/PollCreateUpdate'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/PollCreateUpdate'
      tags:
      - polls
    patch:
      operationId: polls_partial_update
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/PollCreateUpdate'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/PollCreateUpdate'
      tags:
      - polls
    delete:
      operationId: polls_delete
      description: ''
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - polls
    parameters:
    - name: id
      in: path
      description: A UUID string identifying this Poll.
      required: true
      type: string
      format: uuid
  /polls/{id}/close/:
    post:
      operationId: polls_close
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/PollDetail'
      responses:
        '201':
          description: ''
          schema:
            $ref: '#/definitions/PollDetail'
      tags:
      - polls
    parameters:
    - name: id
      in: path
      description: A UUID string identifying this Poll.
      required: true
      type: string
      format: uuid
  /polls/{id}/open/:
    post:
      operationId: polls_open
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/PollDetail'
      responses:
        '201':
          description: ''
          schema:
            $ref: '#/definitions/PollDetail'
      tags:
      - polls
    parameters:
    - name: id
      in: path
      description: A UUID string identifying this Poll.
      required: true
      type: string
      format: uuid
  /polls/{id}/results/:
    get:
      operationId: polls_results
      description: ''
      parameters: []
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/PollResult'
      tags:
      - polls
    parameters:
    - name: id
      in: path
      description: A UUID string identifying this Poll.
      required: true
      type: string
      format: uuid
  /votes/:
    get:
      operationId: votes_list
      description: ''
      parameters:
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        type: string
      - name: page
        in: query
        description: A page number within the paginated result set.
        required: false
        type: integer
      - name: page_size
        in: query
        description: Number of results to return per page.
        required: false
        type: integer
      responses:
        '200':
          description: ''
          schema:
            required:
            - count
            - results
            type: object
            properties:
              count:
                type: integer
              next:
                type: string
                format: uri
                x-nullable: true
              previous:
                type: string
                format: uri
                x-nullable: true
              results:
                type: array
                items:
                  $ref: '#/definitions/Vote'
      tags:
      - votes
    post:
      operationId: votes_create
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/Vote'
      responses:
        '201':
          description: ''
          schema:
            $ref: '#/definitions/Vote'
      tags:
      - votes
    parameters: []
  /votes/{id}/:
    get:
      operationId: votes_read
      description: ''
      parameters: []
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/Vote'
      tags:
      - votes
    put:
      operationId: votes_update
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/Vote'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/Vote'
      tags:
      - votes
    patch:
      operationId: votes_partial_update
      description: ''
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/Vote'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/Vote'
      tags:
      - votes
    delete:
      operationId: votes_delete
      description: ''
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - votes
    parameters:
    - name: id
      in: path
      description: A UUID string identifying this Vote.
      required: true
      type: string
      format: uuid
definitions:
  PollOption:
    required:
    - text
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      poll:
        title: Poll
        type: string
        format: uuid
        readOnly: true
      poll_id:
        title: Poll id
        type: string
        format: uuid
      poll_title:
        title: Poll title
        type: string
        readOnly: true
        minLength: 1
      text:
        title: Text
        type: string
        maxLength: 255
        minLength: 1
      description:
        title: Description
        description: 'Optional: extra context or explanation for this option'
        type: string
      order:
        title: Order
        type: integer
        maximum: 9223372036854775807
        minimum: 0
  PollSummary:
    required:
    - title
    - org
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      title:
        title: Title
        type: string
        maxLength: 255
        minLength: 1
      org:
        title: Org
        type: integer
      org_name:
        title: Org name
        type: string
        readOnly: true
        minLength: 1
      board:
        title: Board
        description: 'Optional: poll can be board-specific or org-wide'
        type: integer
        x-nullable: true
      board_name:
        title: Board name
        type: string
        readOnly: true
        minLength: 1
      document:
        title: Document
        description: 'Optional: link to a document being voted on'
        type: string
        format: uuid
        x-nullable: true
      document_title:
        title: Document title
        type: string
        readOnly: true
        minLength: 1
      status:
        title: Status
        type: string
        enum:
        - draft
        - open
        - closed
      is_anonymous:
        title: Is anonymous
        description: If true, votes are hidden from results (only counts shown).
        type: boolean
      allow_multiple_choices:
        title: Allow multiple choices
        description: If true, a user may vote for multiple options.
        type: boolean
      start_at:
        title: Start at
        type: string
        format: date-time
        x-nullable: true
      end_at:
        title: End at
        type: string
        format: date-time
        x-nullable: true
  PollCreateUpdate:
    required:
    - org
    - title
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      org:
        title: Org
        type: integer
      board:
        title: Board
        description: 'Optional: poll can be board-specific or org-wide'
        type: integer
        x-nullable: true
      document:
        title: Document
        description: 'Optional: link to a document being voted on'
        type: string
        format: uuid
        x-nullable: true
      title:
        title: Title
        type: string
        maxLength: 255
        minLength: 1
      description:
        title: Description
        type: string
      status:
        title: Status
        type: string
        enum:
        - draft
        - open
        - closed
      is_anonymous:
        title: Is anonymous
        description: If true, votes are hidden from results (only counts shown).
        type: boolean
      allow_multiple_choices:
        title: Allow multiple choices
        description: If true, a user may vote for multiple options.
        type: boolean
      start_at:
        title: Start at
        type: string
        format: date-time
        x-nullable: true
      end_at:
        title: End at
        type: string
        format: date-time
        x-nullable: true
  PollDetail:
    required:
    - org
    - title
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      org:
        title: Org
        type: integer
      org_name:
        title: Org name
        type: string
        readOnly: true
        minLength: 1
      board:
        title: Board
        description: 'Optional: poll can be board-specific or org-wide'
        type: integer
        x-nullable: true
      board_name:
        title: Board name
        type: string
        readOnly: true
        minLength: 1
      document:
        title: Document
        description: 'Optional: link to a document being voted on'
        type: string
        format: uuid
        x-nullable: true
      document_title:
        title: Document title
        type: string
        readOnly: true
        minLength: 1
      title:
        title: Title
        type: string
        maxLength: 255
        minLength: 1
      description:
        title: Description
        type: string
      status:
        title: Status
        type: string
        enum:
        - draft
        - open
        - closed
      is_anonymous:
        title: Is anonymous
        description: If true, votes are hidden from results (only counts shown).
        type: boolean
      allow_multiple_choices:
        title: Allow multiple choices
        description: If true, a user may vote for multiple options.
        type: boolean
      start_at:
        title: Start at
        type: string
        format: date-time
        x-nullable: true
      end_at:
        title: End at
        type: string
        format: date-time
        x-nullable: true
      options:
        type: array
        items:
          $ref: '#/definitions/PollOption'
        readOnly: true
      created_by:
        title: Created by
        type: integer
        readOnly: true
        x-nullable: true
      updated_by:
        title: Updated by
        type: integer
        readOnly: true
        x-nullable: true
      created_at:
        title: Created at
        type: string
        format: date-time
        readOnly: true
      updated_at:
        title: Updated at
        type: string
        format: date-time
        readOnly: true
  PollResult:
    required:
    - title
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      title:
        title: Title
        type: string
        maxLength: 255
        minLength: 1
      is_anonymous:
        title: Is anonymous
        description: If true, votes are hidden from results (only counts shown).
        type: boolean
      results:
        title: Results
        type: string
        readOnly: true
  Vote:
    required:
    - poll
    - option
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      poll:
        title: Poll
        type: string
        format: uuid
      option:
        title: Option
        type: string
        format: uuid
      user:
        title: User
        type: integer
        readOnly: true
      user_email:
        title: User email
        type: string
        format: email
        readOnly: true
        minLength: 1
      voted_at:
        title: Voted at
        type: string
        format: date-time
        readOnly: true
