openapi: 3.1.0
info:
  version: 1.0.0
  title: The Mighty Networks Admin AbuseReports Polls API
  description: An API for managing your Mighty Networks network
servers:
- url: https://api.mn.co
  description: Production
security:
- bearerAuth: []
tags:
- name: Polls
  description: Polls and Questions allow members to share opinions and engage with each other
paths:
  /admin/v1/networks/{network_id}/polls:
    get:
      summary: Returns a paginated list of polls and questions in the network
      operationId: list_polls
      tags:
      - Polls
      parameters:
      - name: space_id
        in: query
        required: false
        description: Filter polls by space ID
        schema:
          type: integer
          format: uint64
      - name: page
        in: query
        required: false
        description: Page number for pagination
        schema:
          type: integer
          format: uint64
      - name: per_page
        in: query
        required: false
        description: Items per page (max 100)
        schema:
          type: integer
          format: uint64
      - $ref: '#/components/parameters/networkId'
      responses:
        '200':
          description: Returns a paginated list of polls and questions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PollResponsePaged'
    post:
      summary: Creates a new poll or question in the network
      operationId: create_polls
      tags:
      - Polls
      parameters:
      - $ref: '#/components/parameters/networkId'
      requestBody:
        description: Submit results as JSON
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PollRequest'
      responses:
        '201':
          description: Returns the created poll or question
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PollResponse'
        '404':
          description: Space not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /admin/v1/networks/{network_id}/polls/{id}/:
    get:
      summary: Returns details of a specific poll or question
      operationId: show_poll
      tags:
      - Polls
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the poll or question
        schema:
          type: integer
          format: uint64
      - $ref: '#/components/parameters/networkId'
      responses:
        '200':
          description: Returns the poll or question details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PollResponse'
        '404':
          description: Poll or question not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      summary: Updates a poll or question
      operationId: update_polls
      tags:
      - Polls
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the poll or question
        schema:
          type: integer
          format: uint64
      - $ref: '#/components/parameters/networkId'
      requestBody:
        description: Submit results as JSON
        required: true
        content:
          application/json:
            schema:
              description: Request to update a poll or question
              type: object
              properties:
                title:
                  type: string
                  description: The poll question/title
                description:
                  type: string
                  description: Additional details or context for the poll
      responses:
        '200':
          description: Returns the updated poll or question
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PollResponse'
        '404':
          description: Poll or question not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      summary: Updates a poll or question
      operationId: replace_polls
      tags:
      - Polls
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the poll or question
        schema:
          type: integer
          format: uint64
      - $ref: '#/components/parameters/networkId'
      requestBody:
        description: Submit results as JSON
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PollUpdateRequest'
      responses:
        '200':
          description: Returns the updated poll or question
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PollResponse'
        '404':
          description: Poll or question not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Deletes a poll or question
      operationId: delete_polls
      tags:
      - Polls
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the poll or question
        schema:
          type: integer
          format: uint64
      - $ref: '#/components/parameters/networkId'
      responses:
        '204':
          description: Poll or question successfully deleted
        '404':
          description: Poll or question not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SpaceResponse:
      type: object
      required:
      - created_at
      - id
      - name
      - updated_at
      properties:
        id:
          type: integer
          format: uint64
          description: The record's integer ID
          example: '1234'
        created_at:
          type: string
          format: date-time
          description: The date and time the record was created
          example: '2026-07-05T21:11:41+00:00'
        updated_at:
          type: string
          format: date-time
          description: The date and time the record was last modified
          example: '2026-07-05T21:11:41+00:00'
        name:
          type: string
          description: The Space's name
        collection_id:
          type: integer
          format: uint64
          description: The ID of the collection this space belongs to
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: An error message explaining the problem encountered
    PollChoiceResponse:
      description: A choice option in a multiple choice poll
      type: object
      required:
      - id
      - text
      properties:
        id:
          type: string
          description: The choice ID
        text:
          type: string
          description: The choice text
    UserResponse:
      type: object
      required:
      - admin
      - created_at
      - email
      - id
      - name
      - short_bio
      - updated_at
      properties:
        id:
          type: integer
          format: uint64
          description: The record's integer ID
          example: '1234'
        created_at:
          type: string
          format: date-time
          description: The date and time the record was created
          example: '2026-07-05T21:11:41+00:00'
        updated_at:
          type: string
          format: date-time
          description: The date and time the record was last modified
          example: '2026-07-05T21:11:41+00:00'
        name:
          type: string
          description: The user's full name
        email:
          type: string
          format: email
          description: The user's email address
          example: ada.lovelace@example.com
        short_bio:
          type: string
          description: A short biography of the user
        admin:
          type: boolean
          description: Whether or not the user is an admin of the network
    PollUpdateRequest:
      description: Request to update a poll or question
      type: object
      required: []
      properties:
        title:
          type: string
          description: The poll question/title
        description:
          type: string
          description: Additional details or context for the poll
    PollRequest:
      description: Request to create a poll or question
      type: object
      required:
      - poll_type
      - space_id
      - title
      properties:
        space_id:
          type: integer
          format: uint64
          description: The ID of the space where the poll will be created
        title:
          type: string
          description: The poll question/title
        description:
          type: string
          description: Additional details or context for the poll
        poll_type:
          type: string
          description: 'The type of poll: ''multiple_choice'' (list), ''hot_cold'' (continuous slider), ''percentage'' (percentage allocation), or ''question'' (open-ended text response)'
        choices:
          type: array
          description: Array of choice text strings (required for multiple_choice, hot_cold, and percentage polls)
          items:
            type: string
        notify:
          type: boolean
          description: Whether to notify network members about the new poll
    PollResponse:
      description: A poll or question post
      type: object
      required:
      - comments_enabled
      - created_at
      - creator
      - id
      - permalink
      - post_type
      - space
      - status
      - title
      - updated_at
      properties:
        id:
          type: integer
          format: uint64
          description: The record's integer ID
          example: '1234'
        created_at:
          type: string
          format: date-time
          description: The date and time the record was created
          example: '2026-07-05T21:11:41+00:00'
        updated_at:
          type: string
          format: date-time
          description: The date and time the record was last modified
          example: '2026-07-05T21:11:41+00:00'
        post_type:
          type: string
          description: The type of post (poll or question)
        poll_type:
          type: string
          description: The specific poll type (multiple_choice_poll, hot_cold_poll, percentage_poll)
        title:
          type: string
          description: The poll question/title
        description:
          type: string
          description: The full description of the poll
        creator:
          description: The member who created the poll
          $ref: '#/components/schemas/UserResponse'
        space:
          description: The space where the poll was created
          $ref: '#/components/schemas/SpaceResponse'
        images:
          type: array
          description: Array of image URLs associated with the poll
          items:
            type: string
        choices:
          type: array
          description: The poll choices (for polls with choices)
          items:
            $ref: '#/components/schemas/PollChoiceResponse'
        status:
          type: string
          description: The post's current status
        published_at:
          type: string
          format: date-time
          description: The date the post was published
          example: '2026-07-05T21:11:42+00:00'
        permalink:
          type: string
          description: The permanent URL to the poll
        comments_enabled:
          type: boolean
          description: Whether or not comments are enabled on this poll
        last_activity_at:
          type: string
          format: date-time
          description: The time of last activity on the poll
          example: '2026-07-05T21:11:42+00:00'
  parameters:
    networkId:
      name: network_id
      in: path
      description: The Network's unique integer ID, or subdomain
      required: true
      schema:
        oneOf:
        - type: integer
          description: Unique numeric network ID
          format: uint64
        - type: string
          description: Network subdomain
          format: /^[a-z][a-z0-9-]+$/
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer