openapi: 3.1.0
info:
  version: 1.0.0
  title: The Mighty Networks Admin AbuseReports CustomFields API
  description: An API for managing your Mighty Networks network
servers:
- url: https://api.mn.co
  description: Production
security:
- bearerAuth: []
tags:
- name: CustomFields
  description: Manage custom fields for your network
paths:
  /admin/v1/networks/{network_id}/custom_fields:
    get:
      summary: Return custom fields of the given network
      operationId: list_custom_fields
      tags:
      - CustomFields
      parameters:
      - name: response_type
        in: query
        required: false
        description: 'Filter by response type. Valid values: tag, badge, dropdown_single_select, dropdown_multi_select, text_short, text_long. Invalid values are ignored.'
        schema:
          type: string
      - 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: A paginated set of custom field objects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldResponsePaged'
    post:
      summary: Create a new custom field
      operationId: create_custom_fields
      tags:
      - CustomFields
      parameters:
      - $ref: '#/components/parameters/networkId'
      requestBody:
        description: Submit results as JSON
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldRequest'
      responses:
        '201':
          description: The created custom field object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /admin/v1/networks/{network_id}/custom_fields/{id}/:
    get:
      summary: Return a single custom field by ID
      operationId: show_custom_field
      tags:
      - CustomFields
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the custom field
        schema:
          type: integer
          format: uint64
      - $ref: '#/components/parameters/networkId'
      responses:
        '200':
          description: A custom field object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldResponse'
        '404':
          description: Custom field not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      summary: Update a custom field
      operationId: update_custom_fields
      tags:
      - CustomFields
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the custom field
        schema:
          type: integer
          format: uint64
      - $ref: '#/components/parameters/networkId'
      requestBody:
        description: Submit results as JSON
        required: true
        content:
          application/json:
            schema:
              description: Request body for updating a custom field
              type: object
              properties:
                title:
                  type: string
                  description: The title of the custom field
                  example: Favorite Color
                description:
                  type: string
                  description: Description of the custom field
                  example: Select your favorite color
                placeholder:
                  type: string
                  description: Placeholder text for the custom field input
                  example: Enter your answer here
                status:
                  type: string
                  description: Status of the custom field (visible, hidden, billing_disabled)
                  example: visible
                notify_all_members:
                  type: boolean
                  description: Whether to notify all members when making the custom field visible
                primary:
                  type: boolean
                  description: Whether this is the primary custom field
      responses:
        '200':
          description: The updated custom field object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldResponse'
        '404':
          description: Custom field not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Cannot modify non-host-creatable custom fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      summary: Update a custom field
      operationId: replace_custom_fields
      tags:
      - CustomFields
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the custom field
        schema:
          type: integer
          format: uint64
      - $ref: '#/components/parameters/networkId'
      requestBody:
        description: Submit results as JSON
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldUpdateRequest'
      responses:
        '200':
          description: The updated custom field object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldResponse'
        '404':
          description: Custom field not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Cannot modify non-host-creatable custom fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Delete a custom field
      operationId: delete_custom_fields
      tags:
      - CustomFields
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the custom field
        schema:
          type: integer
          format: uint64
      - $ref: '#/components/parameters/networkId'
      responses:
        '204':
          description: Custom field deleted successfully
        '404':
          description: Custom field not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Cannot delete non-host-creatable custom fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  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-]+$/
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: An error message explaining the problem encountered
    CustomFieldResponse:
      description: Custom Fields are configurable fields that can be added to capture additional member information
      type: object
      required:
      - created_at
      - id
      - response_type
      - 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'
        title:
          type: string
          description: The title of the custom field
          example: Favorite Color
        response_type:
          type: string
          description: The type of response this custom field accepts
          example: dropdown_single_select
    CustomFieldUpdateRequest:
      description: Request body for updating a custom field
      type: object
      required: []
      properties:
        title:
          type: string
          description: The title of the custom field
          example: Favorite Color
        description:
          type: string
          description: Description of the custom field
          example: Select your favorite color
        placeholder:
          type: string
          description: Placeholder text for the custom field input
          example: Enter your answer here
        status:
          type: string
          description: Status of the custom field (visible, hidden, billing_disabled)
          example: visible
        notify_all_members:
          type: boolean
          description: Whether to notify all members when making the custom field visible
        primary:
          type: boolean
          description: Whether this is the primary custom field
    CustomFieldRequest:
      description: Request body for creating a custom field
      type: object
      required:
      - privacy
      - response_by
      - response_type
      - title
      properties:
        title:
          type: string
          description: The title of the custom field
          example: Favorite Color
        description:
          type: string
          description: Description of the custom field
          example: Select your favorite color
        placeholder:
          type: string
          description: Placeholder text for the custom field input
          example: Enter your answer here
        response_type:
          type: string
          description: The type of response this custom field accepts (dropdown_single_select, dropdown_multi_select, text_short, text_long)
          example: dropdown_single_select
        privacy:
          type: string
          description: Privacy level of the custom field (public, private, admin)
          example: public
        response_by:
          type: string
          description: Who can respond to this custom field (hosts_only, individual_member)
          example: individual_member
        allow_ad_hoc:
          type: boolean
          description: Whether members can add their own options (for dropdown types)
        max_responses:
          type: integer
          format: uint64
          description: Maximum number of selections allowed (for dropdown_multi_select, between 2 and 40)
          example: 5
        options:
          type: array
          description: Array of option texts for dropdown types
          items:
            type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer