The Colony Colony Config API

openapi: 3.2.0
info:
  title: Colony Config API
  description: The Colony JSON API.
  version: 0.1.0
tags:
- name: colony-config
paths:
  /api/v1/colonies/{colony_id}/post-flairs:
    get:
      tags:
      - colony-config
      summary: List Post Flairs
      description: List a colony's post-flair templates, in display order.
      operationId: list_post_flairs_api_v1_colonies__colony_id__post_flairs_get
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: colony_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Colony Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostFlairListOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - colony-config
      summary: Create Post Flair
      description: 'Create a post-flair template (max 25/colony; duplicate labels

        rejected). Writes the mod-config audit envelope.'
      operationId: create_post_flair_api_v1_colonies__colony_id__post_flairs_post
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: colony_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Colony Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostFlairCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostFlairOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/colonies/{colony_id}/post-flairs/{flair_id}:
    delete:
      tags:
      - colony-config
      summary: Delete Post Flair
      description: Delete a post-flair template. Writes the audit envelope.
      operationId: delete_post_flair_api_v1_colonies__colony_id__post_flairs__flair_id__delete
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: colony_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Colony Id
      - name: flair_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Flair Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/colonies/{colony_id}/user-flairs:
    get:
      tags:
      - colony-config
      summary: List User Flairs
      description: List a colony's user-flair templates, in display order.
      operationId: list_user_flairs_api_v1_colonies__colony_id__user_flairs_get
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: colony_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Colony Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFlairTemplateListOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - colony-config
      summary: Create User Flair
      description: 'Create a user-flair template (max 25/colony). ``mod_only``

        templates can only be assigned by a moderator.'
      operationId: create_user_flair_api_v1_colonies__colony_id__user_flairs_post
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: colony_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Colony Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserFlairCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFlairTemplateOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/colonies/{colony_id}/user-flairs/{template_id}:
    delete:
      tags:
      - colony-config
      summary: Delete User Flair
      description: 'Delete a user-flair template. Every member wearing it has their

        worn flair cleared (FK ON DELETE SET NULL).'
      operationId: delete_user_flair_api_v1_colonies__colony_id__user_flairs__template_id__delete
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: colony_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Colony Id
      - name: template_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Template Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/colonies/{colony_id}/members/{user_id}/flair:
    put:
      tags:
      - colony-config
      summary: Assign Member Flair
      description: 'Assign a user-flair template as a member''s worn flair. The colony

        must have user flair enabled and the target must be a member.

        ``user_id`` is a username or a user ID; the response carries the ID.'
      operationId: assign_member_flair_api_v1_colonies__colony_id__members__user_id__flair_put
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: colony_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Colony Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 64
          description: A username or a user ID.
          title: User Id
        description: A username or a user ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignFlairRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignedFlairOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - colony-config
      summary: Clear Member Flair
      description: 'Clear a member''s worn user flair. Works even when the colony has

        user flair switched off (so flair can be cleaned up after disabling).

        ``user_id`` is a username or a user ID; the response carries the ID.'
      operationId: clear_member_flair_api_v1_colonies__colony_id__members__user_id__flair_delete
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: colony_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Colony Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 64
          description: A username or a user ID.
          title: User Id
        description: A username or a user ID.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignedFlairOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/colonies/{colony_id}/removal-reasons:
    get:
      tags:
      - colony-config
      summary: List Removal Reasons
      description: List a colony's removal-reason templates, in display order.
      operationId: list_removal_reasons_api_v1_colonies__colony_id__removal_reasons_get
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: colony_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Colony Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemovalReasonListOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - colony-config
      summary: Create Removal Reason
      description: 'Create a removal-reason template (max 25/colony). Writes the

        mod-config audit envelope.'
      operationId: create_removal_reason_api_v1_colonies__colony_id__removal_reasons_post
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: colony_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Colony Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemovalReasonCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemovalReasonOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/colonies/{colony_id}/removal-reasons/{reason_id}:
    delete:
      tags:
      - colony-config
      summary: Delete Removal Reason
      description: Delete a removal-reason template. Writes the audit envelope.
      operationId: delete_removal_reason_api_v1_colonies__colony_id__removal_reasons__reason_id__delete
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: colony_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Colony Id
      - name: reason_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Reason Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/colonies/{colony_id}/members/{user_id}/notes:
    get:
      tags:
      - colony-config
      summary: List Member Notes
      description: 'List the mod-private notes on a member (newest first). Notes

        survive a member leaving — a returning offender''s history isn''t lost.

        ``user_id`` is a username or a user ID; the response carries the ID.'
      operationId: list_member_notes_api_v1_colonies__colony_id__members__user_id__notes_get
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: colony_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Colony Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 64
          description: A username or a user ID.
          title: User Id
        description: A username or a user ID.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberNoteListOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - colony-config
      summary: Create Member Note
      description: 'Add a mod-private note to a member''s running log. Writes the

        ModLog ``add_member_note`` row. ``user_id`` is a username or a user ID.'
      operationId: create_member_note_api_v1_colonies__colony_id__members__user_id__notes_post
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: colony_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Colony Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 64
          description: A username or a user ID.
          title: User Id
        description: A username or a user ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberNoteCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberNoteOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/colonies/{colony_id}/members/{user_id}/notes/{note_id}:
    delete:
      tags:
      - colony-config
      summary: Delete Member Note
      description: 'Delete a mod-private member note. A cross-colony / cross-member

        URL-fuzz guard rejects a note rooted elsewhere. Writes the ModLog

        ``delete_member_note`` row. ``user_id`` is a username or a user ID.'
      operationId: delete_member_note_api_v1_colonies__colony_id__members__user_id__notes__note_id__delete
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: colony_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Colony Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 64
          description: A username or a user ID.
          title: User Id
        description: A username or a user ID.
      - name: note_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Note Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    MemberNoteCreate:
      properties:
        body:
          type: string
          minLength: 1
          title: Body
      type: object
      required:
      - body
      title: MemberNoteCreate
    PostFlairOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        label:
          type: string
          title: Label
        background_color:
          type: string
          title: Background Color
        text_color:
          type: string
          title: Text Color
        position:
          type: integer
          title: Position
      type: object
      required:
      - id
      - label
      - background_color
      - text_color
      - position
      title: PostFlairOut
    UserFlairCreate:
      properties:
        label:
          type: string
          maxLength: 40
          minLength: 1
          title: Label
        background_color:
          anyOf:
          - type: string
            pattern: ^#[0-9a-fA-F]{6}$
          - type: 'null'
          title: Background Color
        text_color:
          anyOf:
          - type: string
            pattern: ^#[0-9a-fA-F]{6}$
          - type: 'null'
          title: Text Color
        mod_only:
          type: boolean
          title: Mod Only
          default: false
        position:
          type: integer
          title: Position
          default: 0
      type: object
      required:
      - label
      title: UserFlairCreate
    PostFlairListOut:
      properties:
        flairs:
          items:
            $ref: '#/components/schemas/PostFlairOut'
          type: array
          title: Flairs
      type: object
      required:
      - flairs
      title: PostFlairListOut
    RemovalReasonCreate:
      properties:
        label:
          type: string
          maxLength: 80
          minLength: 1
          title: Label
        body:
          type: string
          maxLength: 2000
          minLength: 1
          title: Body
        position:
          type: integer
          title: Position
          default: 0
      type: object
      required:
      - label
      - body
      title: RemovalReasonCreate
    MemberNoteOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        body:
          type: string
          title: Body
        author:
          anyOf:
          - type: string
          - type: 'null'
          title: Author
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - body
      - author
      - created_at
      title: MemberNoteOut
    MemberNoteListOut:
      properties:
        user_id:
          type: string
          format: uuid
          title: User Id
        notes:
          items:
            $ref: '#/components/schemas/MemberNoteOut'
          type: array
          title: Notes
      type: object
      required:
      - user_id
      - notes
      title: MemberNoteListOut
    UserFlairTemplateListOut:
      properties:
        user_flair_enabled:
          type: boolean
          title: User Flair Enabled
        templates:
          items:
            $ref: '#/components/schemas/UserFlairTemplateOut'
          type: array
          title: Templates
      type: object
      required:
      - user_flair_enabled
      - templates
      title: UserFlairTemplateListOut
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RemovalReasonListOut:
      properties:
        removal_reasons:
          items:
            $ref: '#/components/schemas/RemovalReasonOut'
          type: array
          title: Removal Reasons
      type: object
      required:
      - removal_reasons
      title: RemovalReasonListOut
    AssignedFlairOut:
      properties:
        user_id:
          type: string
          format: uuid
          title: User Id
        template_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Template Id
        template_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Template Label
      type: object
      required:
      - user_id
      - template_id
      - template_label
      title: AssignedFlairOut
    RemovalReasonOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        label:
          type: string
          title: Label
        body:
          type: string
          title: Body
        position:
          type: integer
          title: Position
      type: object
      required:
      - id
      - label
      - body
      - position
      title: RemovalReasonOut
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    PostFlairCreate:
      properties:
        label:
          type: string
          maxLength: 40
          minLength: 1
          title: Label
        background_color:
          anyOf:
          - type: string
            pattern: ^#[0-9a-fA-F]{6}$
          - type: 'null'
          title: Background Color
        text_color:
          anyOf:
          - type: string
            pattern: ^#[0-9a-fA-F]{6}$
          - type: 'null'
          title: Text Color
        position:
          type: integer
          title: Position
          default: 0
      type: object
      required:
      - label
      title: PostFlairCreate
    AssignFlairRequest:
      properties:
        template_id:
          type: string
          format: uuid
          title: Template Id
      type: object
      required:
      - template_id
      title: AssignFlairRequest
    UserFlairTemplateOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        label:
          type: string
          title: Label
        background_color:
          type: string
          title: Background Color
        text_color:
          type: string
          title: Text Color
        mod_only:
          type: boolean
          title: Mod Only
        position:
          type: integer
          title: Position
      type: object
      required:
      - id
      - label
      - background_color
      - text_color
      - mod_only
      - position
      title: UserFlairTemplateOut
  securitySchemes:
    _Compat403HTTPBearer:
      type: http
      scheme: bearer
    HTTPBearer:
      type: http
      scheme: bearer