components:
  schemas:
    TypeId:
      description: UUID with type prefix
      type: string
      example: us_01hxcvk1hjexere4pvtrj0ymqq
    AIAgentAssignment:
      description: >-
        Complete AI agent assignment record representing an active bot
        deployment.
                Contains the assignment configuration, timestamps, and scope information.
                The RAG pipeline reads these assignments to enable bot interactions in their designated areas.
      required:
        - assignmentId
        - agentId
        - assignmentType
        - createdAt
        - updatedAt
      type: object
      properties:
        assignmentId:
          description: Unique TypeId for this assignment
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: aia_abc123
        agentId:
          description: TypeId of the bot user assigned. References a user with isBot=true.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: usr_bot456
        assignmentType:
          description: |-
            Assignment type determining where the bot operates.
                        Valid values: GLOBAL, GROUP, FORUM, FORUM_CATEGORY, GROUP_CHANNEL
          type: string
          allOf:
            - $ref: '#/components/schemas/AIAgentAssignmentType'
          example: FORUM
        resourceId:
          description: |-
            TypeId of the specific resource this assignment is scoped to.
                        Null for GLOBAL assignments.
                        Contains forum_id for FORUM, category_id for FORUM_CATEGORY, channel_id for GROUP_CHANNEL assignments.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: frm_xyz123
          nullable: true
        groupId:
          description: |-
            TypeId of the group this assignment belongs to.
                        Present for group-scoped assignments (GROUP, FORUM, FORUM_CATEGORY, GROUP_CHANNEL).
                        Null for GLOBAL assignments.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: grp_abc456
          nullable: true
        createdAt:
          description: ISO 8601 timestamp when this assignment was created
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2024-01-15T10:30:00Z'
        updatedAt:
          description: ISO 8601 timestamp when this assignment was last updated
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2024-01-15T10:30:00Z'
      example:
        assignmentId: aia_abc123
        agentId: usr_bot456
        assignmentType: FORUM
        resourceId: frm_xyz123
        groupId: grp_abc456
        createdAt: '2024-01-15T10:30:00Z'
        updatedAt: '2024-01-15T10:30:00Z'
    AIAgentAssignmentCreate:
      description: |-
        Request to create an AI agent assignment.
                Specifies which bot to activate and where it should operate.
                The agentId must refer to a user account with isBot=true.
                Validation rules:
                - For GLOBAL assignments: resourceId must be null
                - For GROUP assignments: resourceId must be null or match the group ID
                - For FORUM assignments: resourceId must be a valid forum TypeId
                - For FORUM_CATEGORY assignments: resourceId must be a valid category TypeId
                - For GROUP_CHANNEL assignments: resourceId must be a valid channel TypeId
      required:
        - agentId
        - assignmentType
      type: object
      properties:
        agentId:
          description: >-
            TypeId of the bot user to assign. Must be a valid user with
            isBot=true.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: usr_bot456
        assignmentType:
          description: |-
            Assignment type determining the bot's operational scope.
                        Valid values: GLOBAL, GROUP, FORUM, FORUM_CATEGORY, GROUP_CHANNEL
          type: string
          allOf:
            - $ref: '#/components/schemas/AIAgentAssignmentType'
          example: GLOBAL
        resourceId:
          description: |-
            TypeId of the resource to scope the assignment to.
                        Must be null for GLOBAL assignments.
                        Must be null or match the group ID for GROUP assignments.
                        Required for FORUM (forum_id), FORUM_CATEGORY (category_id), GROUP_CHANNEL (channel_id) assignments.
                        The TypeId type must match the assignment type.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: frm_xyz123
          nullable: true
      example:
        agentId: usr_bot456
        assignmentType: GLOBAL
        resourceId: null
    AIAgentAssignmentType:
      description: |-
        Assignment scope/type that determines where an AI agent operates.
                - GLOBAL: Bot operates platform-wide across all content
                - GROUP: Bot operates within a specific group
                - FORUM: Bot operates within a specific forum
                - FORUM_CATEGORY: Bot operates within a specific forum category
                - GROUP_CHANNEL: Bot operates within a specific group channel
      enum:
        - GLOBAL
        - GROUP
        - FORUM
        - FORUM_CATEGORY
        - GROUP_CHANNEL
      type: string
    Account:
      required:
        - id
        - createdAt
        - updatedAt
      type: object
      properties:
        id:
          description: Internal account id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: act_ytweuysdjfhguyt
        email:
          description: Account email
          type: string
          example: john@example.com
          nullable: true
        password:
          type: string
          nullable: true
        phone:
          description: Account phone
          type: string
          example: '+12345678901'
          nullable: true
        createdAt:
          $ref: '#/components/schemas/Instant'
        updatedAt:
          $ref: '#/components/schemas/Instant'
    AccountCreate:
      description: >-
        Parameters for creating a new account with a primary user. The account
        will be created with email/password authentication and a single user
        profile.
      required:
        - username
        - displayName
        - email
        - password
      type: object
      properties:
        username:
          description: Username of the main user
          type: string
          example: john_smith
        displayName:
          description: Display Name of the main user
          maxLength: 56
          minLength: 1
          type: string
          example: John Smith
        email:
          description: Accounts' email
          type: string
          example: email@gmail.com
        password:
          description: Account password, enforced by password policy
          type: string
          example: PassW0rd!
        inviteCode:
          description: Optional invite code
          type: string
          example: abcd-efgh-1234
          nullable: true
    AccountWithUser:
      description: >-
        Complete account information including the account details and all
        associated users. An account represents the authentication entity while
        users represent the public profiles.
      required:
        - account
        - users
      type: object
      properties:
        account:
          description: Account details including email, login type, and creation date
          type: object
          allOf:
            - $ref: '#/components/schemas/Account'
        users:
          description: >-
            Non-empty list of users associated with this account. Most accounts
            have one user, but multiple users are supported.
          type: array
          items:
            $ref: '#/components/schemas/UserFull'
        selectedUserId:
          description: >-
            ID of currently selected user. If not provided, the first user is
            selected
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: usr_kjhauygmxcvkhwe
          nullable: true
    AccountWithUserAndToken:
      required:
        - account
        - users
        - token
      type: object
      properties:
        account:
          $ref: '#/components/schemas/Account'
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserFull'
        token:
          $ref: '#/components/schemas/Token'
    ActionModel:
      required:
        - name
        - description
      type: object
      properties:
        name:
          type: string
        description:
          type: string
    ActionProperties:
      required:
        - extension
      type: object
      properties:
        extension:
          type: string
        width:
          format: int32
          type: integer
          nullable: true
        height:
          format: int32
          type: integer
          nullable: true
        rotation:
          format: int32
          type: integer
        thumbnailSecond:
          format: double
          type: number
          nullable: true
    ActorType:
      description: |2-

                    Types that an Actor can be assigned. Coincide with ActivityPub Actor types:
                    * APPLICATION: Apps will have this type
                    * GROUP: Interest Groups and Generic Groups wil have this type
                    * ORGANIZATION: Formal Organizations such as Companies, Institutions, etc. will have this type
                    * PERSON: Individual people will have this type
                    * SERVICE: Bots, Services, and other automated tools which are not also Apps will have this type
                
      enum:
        - Application
        - Group
        - Organization
        - Person
        - Service
      type: string
    AddEmailRequest:
      description: Params to add email to account
      required:
        - email
        - password
      type: object
      properties:
        email:
          description: New email
          type: string
          example: user@gmail.com
        password:
          description: New password, enforced by password policy
          type: string
          example: PassW0rd!
    AddPhoneRequest:
      required:
        - phone
      type: object
      properties:
        phone:
          description: Phone number
          type: string
          example: '+12345678901'
        code:
          format: int32
          description: Confirmation code
          type: integer
          example: 854882
          nullable: true
    Address:
      description: Physical address
      required:
        - id
        - data
        - createdAt
        - updatedAt
      type: object
      properties:
        id:
          format: int32
          description: Internal address id
          type: integer
        data:
          description: Address data
          type: object
          allOf:
            - $ref: '#/components/schemas/AddressData'
        latitude:
          format: double
          description: Address latitude
          type: number
          nullable: true
        longitude:
          format: double
          description: Address longitude
          type: number
          nullable: true
        createdAt:
          $ref: '#/components/schemas/Instant'
        updatedAt:
          $ref: '#/components/schemas/Instant'
    AddressData:
      description: Address variant
      required:
        - formatted
      type: object
      properties:
        formatted:
          description: Formatted address
          type: string
          example: Adriaen Van Ostadestraat 53, 4703 NT Roosendaal, Netherlands
        name:
          description: Name
          type: string
          example: Casa Vacanze
          nullable: true
        country:
          description: Country
          type: string
          example: USA
          nullable: true
        countryCode:
          description: Country two letter name
          type: string
          example: us
          nullable: true
        region:
          description: Region
          type: string
          example: Massachusetts
          nullable: true
        regionCode:
          description: Region Code
          type: string
          example: MA
          nullable: true
        subRegion:
          description: Sub-region
          type: string
          example: Newton Heights
          nullable: true
        locality:
          description: Locality
          type: string
          example: Madrid
          nullable: true
        street:
          description: Street
          type: string
          example: Adriaen Van Ostadestraat
          nullable: true
        postalCode:
          description: Address postal code
          type: string
          example: 4703 NT
          nullable: true
        houseNumber:
          description: House number
          type: string
          example: '23'
          nullable: true
        longitude:
          format: double
          description: Longitude
          type: number
          example: 4.437564
          nullable: true
        latitude:
          format: double
          description: Latitude
          type: number
          example: 51.534581
          nullable: true
        timeZone:
          description: Time zone name
          type: string
          example: Europe/Amsterdam
          nullable: true
        plusCode:
          description: Short code
          type: string
          example: 9F36GCMQ+R2
          nullable: true
        serviceId:
          description: Service ID
          type: string
          example: geoapify
          nullable: true
        placeId:
          description: Service place id
          type: string
          nullable: true
    AllowedDomain:
      required:
        - domain
        - createdAt
      type: object
      properties:
        domain:
          description: The domain name that is allowed to federate with this instance
          type: string
          example: mastodon.social
        createdAt:
          description: Timestamp when the domain was added to the allowlist
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2024-01-15T10:30:00Z'
    AllowedDomainReq:
      required:
        - domain
      type: object
      properties:
        domain:
          description: The domain name to add to the allowlist
          pattern: >-
            ^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]?(?:\.[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9]?)*$
          type: string
          example: example.com
    Answer:
      description: >-
        An answer to a specific group entry question. The answer format must
        match the question type: TEXT questions require textAnswer,
        SINGLE_CHOICE requires exactly one selectedChoice index, MULTIPLE_CHOICE
        requires one or more selectedChoice indices.
      required:
        - questionId
        - questionType
        - selectedChoices
      type: object
      properties:
        questionId:
          description: The unique identifier of the question being answered
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: qu_01hz1f0gs9fe4a37jzvzn9m96k
        questionType:
          description: The type of the question - must match the actual question type
          type: string
          allOf:
            - $ref: '#/components/schemas/QuestionType'
        textAnswer:
          description: Free-form text answer for TEXT type questions (max 500 characters)
          type: string
          example: I want to join to share my expertise and learn from others
          nullable: true
        selectedChoices:
          description: >-
            Zero-based indices of selected choices for SINGLE_CHOICE or
            MULTIPLE_CHOICE questions
          type: array
          items:
            format: int32
            type: integer
          example:
            - 0
            - 2
    AppData:
      required:
        - id
        - ownerId
        - type
        - data
        - createdAt
        - updatedAt
      type: object
      properties:
        id:
          description: Unique identifier for the app data
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: ad_01hq8c8em5hj1vr2f4h1t9db9q
        applicationId:
          description: Optional application ID that this data belongs to
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: ap_01hq8c8em5hj1vr2f4h1t9db9q
          nullable: true
        ownerId:
          description: >-
            Owner identifier of the data. Can be a user ID, group ID,
            user-in-group format userId:groupId, or 'platform'
          type: string
          example: us_01hq8c8em5hj1vr2f4h1t9db9q
        type:
          description: Type identifier for categorizing the data
          type: string
          example: user_profile
        tags:
          description: Optional list of tags for additional categorization
          type: array
          items:
            type: string
          example:
            - personal
            - profile
          nullable: true
        data:
          description: JSON string containing the actual data payload
          type: string
          example: '{"name": "John Doe", "bio": "Developer"}'
        createdAt:
          description: Timestamp when the data was created
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2024-03-20T10:15:30Z'
        updatedAt:
          description: Timestamp when the data was last updated
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2024-03-20T10:15:30Z'
    AppScheme:
      enum:
        - http
        - https
      type: string
    Application:
      required:
        - id
        - name
        - manifest
        - updatedAt
      type: object
      properties:
        id:
          $ref: '#/components/schemas/TypeId'
        name:
          type: string
        manifest:
          $ref: '#/components/schemas/Manifest'
        enabled:
          type: boolean
        updatedAt:
          $ref: '#/components/schemas/Instant'
    ApplicationDeveloper:
      required:
        - name
        - website
      type: object
      properties:
        name:
          type: string
        website:
          type: string
    ApplicationType:
      enum:
        - REGULAR
        - ERROR
        - TOOLBAR
      type: string
    ApplicationVisibility:
      enum:
        - PUBLIC
        - UNLISTED
      type: string
    ApplicationWithStats:
      required:
        - id
        - name
        - manifest
        - updatedAt
      type: object
      properties:
        id:
          $ref: '#/components/schemas/TypeId'
        name:
          type: string
        manifest:
          $ref: '#/components/schemas/Manifest'
        enabled:
          type: boolean
        updatedAt:
          $ref: '#/components/schemas/Instant'
        usersCount:
          format: int32
          type: integer
    AssignGlobalUsernameRequest:
      description: >-
        Request payload for assigning or unassigning a global username to a
        channel. Global usernames provide platform-wide access to public
        channels and must be unique across the entire system.
      required:
        - globalUsername
      type: object
      properties:
        globalUsername:
          description: >-
            Global username to assign to the channel. Must be unique
            platform-wide. Set to null to remove the global username. Only
            available for public channels in public groups.
          type: string
          example: platform-updates
          nullable: true
    Attachment:
      required:
        - id
      type: object
      properties:
        id:
          type: string
        description:
          type: string
          nullable: true
    AuditLogAction:
      enum:
        - CREATE
        - UPDATE
        - DELETE
        - PURGE
        - ROLE_CHANGE
        - USERNAME_CHANGE
        - EMAIL_CHANGE
        - PHONE_CHANGE
        - STATE_CHANGE
        - APPROVE
        - REJECT
        - INSTALL
        - ENABLE
        - DISABLE
        - IMPERSONATE_REQUEST
        - IMPERSONATE
        - ACTION
        - JOIN
        - LEAVE
        - INVITE
        - JOIN_REQUEST
      type: string
    AuditLogGroup:
      enum:
        - ACCOUNT
        - USER
        - APP
        - RULE
        - SIGNUP
        - POST
        - DOMAIN_BLOCK
        - EMAIL_BLOCK
        - EMAIL_ALLOW
        - GROUP
        - GROUP_MEMBER
        - GROUP_QUESTION
        - SERVICE
      type: string
    AuditLogRecord:
      required:
        - logGroup
        - logAction
        - happenedAt
        - ip
        - executor
        - data
      type: object
      properties:
        logGroup:
          description: Group of the audit log
          type: string
          allOf:
            - $ref: '#/components/schemas/AuditLogGroup'
          example: ACCOUNT
        logAction:
          description: Action performed in the audit log
          type: string
          allOf:
            - $ref: '#/components/schemas/AuditLogAction'
          example: CREATE
        happenedAt:
          description: Timestamp when the action happened
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2023-01-01T00:00:00Z'
        ip:
          description: IP address from which the action was performed
          type: object
          allOf:
            - $ref: '#/components/schemas/InetAddress'
        executor:
          description: Entity that executed the action
          type: object
          allOf:
            - $ref: '#/components/schemas/Executor'
        data:
          description: Additional data related to the action
          type: object
          additionalProperties: {}
    AuditLogResult:
      required:
        - list
        - total
      type: object
      properties:
        list:
          description: List of audit log records
          type: array
          items:
            $ref: '#/components/schemas/AuditLogRecord'
        total:
          format: int32
          description: Total number of records matching the query
          type: integer
          example: 42
    AuthPhoneRequest:
      required:
        - phone
      type: object
      properties:
        phone:
          description: Phone number
          type: string
          example: '+12345678901'
        code:
          format: int32
          description: Confirmation code
          type: integer
          example: 854882
          nullable: true
    AuthRequest:
      description: Authentication with email/username & password
      required:
        - login
        - password
      type: object
      properties:
        login:
          description: Email or username
          maxLength: 255
          minLength: 1
          type: string
          example: john_smith@gmail.com or jonh_smith
        password:
          description: Account's password
          maxLength: 64
          minLength: 1
          type: string
          example: PassW0rd!
    AuthenticatorSelectionCriteria:
      type: object
      properties:
        authenticatorAttachment:
          type: string
          nullable: true
        requireResidentKey:
          type: boolean
          nullable: true
        residentKey:
          type: string
          nullable: true
        userVerification:
          type: string
          nullable: true
    Birthday:
      description: User's birthday preferences
      required:
        - show
      type: object
      properties:
        date:
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        show:
          $ref: '#/components/schemas/BirthdayShowOptions'
    BirthdayShowOptions:
      enum:
        - NONE
        - YEAR
        - FULL
        - DATE
      type: string
    BlockDomainReq:
      description: Params to block domain
      required:
        - domain
        - publicComment
        - state
        - privateComment
      type: object
      properties:
        domain:
          description: >-
            Domain to block. Can be subdomain, i.e. example.com will block
            sub.example.com
          pattern: \S
          type: string
          example: example.com
        publicComment:
          description: A comment visible to the general public
          type: string
          example: Violence
        state:
          $ref: '#/components/schemas/DomainBlockState'
        rejectMedia:
          description: >-
            Rejects any media coming from the domain and removes already
            downloaded. Ignored for SUSPEND
          type: boolean
        rejectReports:
          description: Ignore all reports coming from this domain. Ignored for SUSPEND
          type: boolean
        privateComment:
          description: Comment available only for moderators
          type: string
        obfuscate:
          description: Partially obfuscate the domain name in the list
          type: boolean
    BlockEmailRequest:
      description: Request to block an email pattern
      required:
        - pattern
        - reason
      type: object
      properties:
        pattern:
          description: Email pattern to block (can be full email or domain)
          pattern: \S
          type: string
          example: baduser@example.com
        reason:
          description: Reason for blocking this email pattern
          pattern: \S
          type: string
          example: Spam account
    BlockedDomain:
      required:
        - domain
        - publicComment
        - state
        - rejectMedia
        - rejectReports
        - privateComment
        - obfuscate
        - createdAt
        - updatedAt
      type: object
      properties:
        domain:
          description: >-
            The blocked domain name. May be obfuscated in public endpoints if
            obfuscate flag is set.
          type: string
          example: spam.example
        publicComment:
          description: Public-facing comment explaining why the domain was blocked
          type: string
          example: Repeated spam violations
        state:
          description: The severity level of the domain block
          enum:
            - SUSPEND
            - LIMIT
            - NOOP
          type: string
        rejectMedia:
          description: Whether to reject and remove media files from this domain
          type: boolean
          example: true
        rejectReports:
          description: Whether to ignore reports coming from this domain
          type: boolean
          example: false
        privateComment:
          description: Internal comment visible only to moderators and administrators
          type: string
          example: Multiple verified spam reports from trusted instances
        obfuscate:
          description: Whether to partially obfuscate the domain name in public listings
          type: boolean
          example: false
        createdAt:
          description: Timestamp when the domain block was created
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2024-01-15T10:30:00Z'
        updatedAt:
          description: Timestamp when the domain block was last updated
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2024-01-16T14:20:00Z'
    BulkImport:
      required:
        - userId
        - type
        - state
        - createdAt
        - updatedAt
      type: object
      properties:
        bulkImportId:
          format: int64
          type: integer
        userId:
          $ref: '#/components/schemas/TypeId'
        type:
          $ref: '#/components/schemas/BulkImportType'
        state:
          $ref: '#/components/schemas/BulkImportState'
        overwrite:
          type: boolean
        originalFilename:
          type: string
          nullable: true
        likelyMismatched:
          type: boolean
        totalItems:
          format: int64
          type: integer
          nullable: true
        importedItems:
          format: int64
          type: integer
          nullable: true
        processedItems:
          format: int64
          type: integer
          nullable: true
        createdAt:
          $ref: '#/components/schemas/Instant'
        updatedAt:
          $ref: '#/components/schemas/Instant'
    BulkImportState:
      enum:
        - PENDING
        - SCHEDULED
        - IN_PROGRESS
        - COMPLETED
      type: string
    BulkImportType:
      enum:
        - FOLLOWING
        - BLOCK
        - MUTE
        - DOMAIN_BLOCK
        - BOOKMARKS
        - LISTS
      type: string
    CPCertification:
      description: Candidate's Certifications
      required:
        - name
        - authority
        - dateObtained
      type: object
      properties:
        name:
          description: The name of the certificate
          maxLength: 256
          type: string
          nullable: true
        authority:
          description: The name of the authority that granted the certificate
          maxLength: 256
          type: string
          nullable: true
        dateObtained:
          description: The date the certificate was obtained
          type: string
          allOf:
            - $ref: '#/components/schemas/LocalDate'
          nullable: true
    CPContact:
      description: Candidate's Contact Info
      type: object
      properties:
        email:
          description: Candidate's email
          maxLength: 256
          pattern: ^[A-Za-z0-9+_.-]+@(.+)$
          type: string
          nullable: true
        phone:
          description: Candidate's phone number
          maxLength: 32
          pattern: ^\+[1-9]{1}[0-9\s]{3,14}$
          type: string
          nullable: true
        website:
          description: Candidate's website
          maxLength: 256
          pattern: ^(https?|ftp)://[^\s/$.?#].[^\s]*$
          type: string
          nullable: true
        linkedin:
          description: Candidate's linkedin
          maxLength: 128
          pattern: ^(https?|ftp)://[^\s/$.?#].[^\s]*$
          type: string
          nullable: true
        github:
          description: Candidate's github
          maxLength: 128
          pattern: ^(https?|ftp)://[^\s/$.?#].[^\s]*$
          type: string
          nullable: true
        bitbucket:
          description: Candidate's bitbucket
          maxLength: 128
          pattern: ^(https?|ftp)://[^\s/$.?#].[^\s]*$
          type: string
          nullable: true
        x:
          description: Candidate's X
          maxLength: 128
          pattern: ^(https?|ftp)://[^\s/$.?#].[^\s]*$
          type: string
          nullable: true
    CPCourse:
      description: Candidate's courses
      required:
        - name
        - institution
        - startDate
      type: object
      properties:
        name:
          description: The name of the course
          maxLength: 256
          type: string
          nullable: true
        institution:
          description: The name of the institution/organization supplying the course
          maxLength: 256
          type: string
          nullable: true
        startDate:
          description: The start date
          type: string
          allOf:
            - $ref: '#/components/schemas/LocalDate'
          nullable: true
        endDate:
          description: The graduation/end date
          type: string
          allOf:
            - $ref: '#/components/schemas/LocalDate'
          nullable: true
    CPData:
      description: Employee Profile data
      required:
        - firstName
        - lastName
        - contact
        - location
        - occupation
      type: object
      properties:
        firstName:
          description: The first name of the employee
          maxLength: 64
          type: string
          nullable: true
        lastName:
          description: The last name of the employee
          maxLength: 64
          type: string
          nullable: true
        fullName:
          description: The full name of the candidate
          maxLength: 129
          type: string
          nullable: true
        contact:
          description: Contact information.  Phones, emails, websites, etc...
          type: object
          allOf:
            - $ref: '#/components/schemas/CPContact'
          nullable: true
        location:
          description: Location/Address
          type: object
          allOf:
            - $ref: '#/components/schemas/CPLocation'
          nullable: true
        occupation:
          description: Current title/position/job
          maxLength: 128
          type: string
          nullable: true
        personal:
          description: Any relevant personal information
          maxLength: 4092
          type: string
          nullable: true
        summary:
          description: Summary of candidate's offering and goals
          maxLength: 4092
          type: string
          nullable: true
        skills:
          description: The list of candidate's skills
          maxItems: 128
          type: array
          items:
            $ref: '#/components/schemas/CPSkill'
          nullable: true
        history:
          description: The list of candidate's previous jobs
          maxItems: 64
          type: array
          items:
            $ref: '#/components/schemas/CPHistory'
          nullable: true
        education:
          description: The list of candidate's education items
          maxItems: 64
          type: array
          items:
            $ref: '#/components/schemas/CPEducation'
          nullable: true
        courses:
          description: The list of candidate's completed courses
          maxItems: 64
          type: array
          items:
            $ref: '#/components/schemas/CPCourse'
          nullable: true
        languages:
          description: The list of candidate's languages
          maxItems: 32
          type: array
          items:
            $ref: '#/components/schemas/CPLanguage'
          nullable: true
        certifications:
          description: The list of candidate's certification
          maxItems: 64
          type: array
          items:
            $ref: '#/components/schemas/CPCertification'
          nullable: true
        projects:
          description: The list of candidate's projects
          maxItems: 64
          type: array
          items:
            $ref: '#/components/schemas/CPProject'
          nullable: true
    CPEducation:
      description: Candidate's Education
      required:
        - school
        - degree
        - location
        - startDate
      type: object
      properties:
        school:
          description: The name of the school
          maxLength: 128
          type: string
          nullable: true
        degree:
          description: The earned degree
          maxLength: 128
          type: string
          nullable: true
        location:
          description: The location of the school
          maxLength: 128
          type: string
          nullable: true
        startDate:
          description: The start date
          type: string
          allOf:
            - $ref: '#/components/schemas/LocalDate'
          nullable: true
        endDate:
          description: The graduation/end date
          type: string
          allOf:
            - $ref: '#/components/schemas/LocalDate'
          nullable: true
        description:
          description: The additional description
          maxLength: 4092
          type: string
          nullable: true
    CPHistory:
      description: Candidate's Work history
      required:
        - title
        - company
        - location
        - startDate
      type: object
      properties:
        title:
          description: Position held/Title
          maxLength: 256
          type: string
          nullable: true
        company:
          description: Company name
          maxLength: 256
          type: string
          nullable: true
        location:
          description: Company location/country/state/city
          maxLength: 128
          type: string
          nullable: true
        startDate:
          description: Candidate's start date for the position
          type: string
          allOf:
            - $ref: '#/components/schemas/LocalDate'
          nullable: true
        endDate:
          description: Candidate's end date for the position
          type: string
          allOf:
            - $ref: '#/components/schemas/LocalDate'
          nullable: true
        description:
          description: The position description, candidate's responsibilities, etc.
          maxLength: 9184
          type: string
          nullable: true
    CPLanguage:
      description: Candidate's Languages
      required:
        - name
        - level
      type: object
      properties:
        name:
          description: The official name of language
          maxLength: 64
          type: string
          nullable: true
        level:
          description: The mastery level achieved
          maxLength: 64
          type: string
          nullable: true
    CPLocation:
      description: Candidate's CPLocation/Address Info
      required:
        - city
        - stateProvince
        - country
      type: object
      properties:
        city:
          description: Candidate's city
          maxLength: 64
          type: string
          nullable: true
        stateProvince:
          description: Candidate's state/province
          maxLength: 64
          type: string
          nullable: true
        country:
          description: Candidate's country
          maxLength: 64
          type: string
          nullable: true
        postcode:
          description: Candidate's postal code
          maxLength: 32
          type: string
          nullable: true
        timezone:
          description: Candidate's time zone
          maxLength: 32
          type: string
          nullable: true
    CPProject:
      description: Candidate's Projects
      required:
        - name
      type: object
      properties:
        name:
          description: The name of the project
          maxLength: 256
          type: string
          nullable: true
        description:
          description: The description of the project
          maxLength: 4092
          type: string
          nullable: true
        url:
          description: The URL/website of the project
          maxLength: 256
          type: string
          nullable: true
    CPSkill:
      description: Candidate's skill
      required:
        - name
        - level
      type: object
      properties:
        name:
          description: Skill name
          maxLength: 128
          type: string
          nullable: true
        level:
          description: Mastery level
          maxLength: 64
          type: string
          nullable: true
    Capability:
      required:
        - id
        - version
      type: object
      properties:
        id:
          type: string
        version:
          type: string
        enabled:
          type: boolean
    CaptchaVerificationParams:
      description: Params to verify captcha
      required:
        - hash
        - captchaToken
      type: object
      properties:
        hash:
          description: Registration hash
          pattern: \S
          type: string
          example: aaaaaaa-ccccccccccccc-wwwwwwwww
        captchaToken:
          description: Captcha token
          pattern: \S
          type: string
          example: 10010101-aaaa-bbbb-cccc-100000000001
    Card:
      description: >-
        Link preview card for displaying metadata about an external URL embedded
        in a post
      required:
        - url
        - createdAt
      type: object
      properties:
        url:
          description: URL being referenced
          type: string
          nullable: true
        title:
          description: Title of the linked resource
          type: string
          nullable: true
        description:
          description: Description of the linked resource
          type: string
          nullable: true
        icon:
          description: Favicon URL
          type: string
          nullable: true
        image:
          description: Preview image URL
          type: string
          nullable: true
        imageAlt:
          description: Alt text for the preview image
          type: string
          nullable: true
        publisher:
          description: Information about the website/provider
          type: object
          allOf:
            - $ref: '#/components/schemas/Publisher'
          nullable: true
        oembedHtml:
          description: HTML snippet to embed the link (from oEmbed), e.g., an iframe
          type: string
          nullable: true
        createdAt:
          description: When the card data was fetched/created
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
        expiresAt:
          description: When the card data should be considered stale
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
    Category:
      description: Category response model
      required:
        - id
        - forumId
        - name
        - displayName
        - description
        - meta
        - tagsAllowed
      type: object
      properties:
        id:
          $ref: '#/components/schemas/TypeId'
        forumId:
          $ref: '#/components/schemas/TypeId'
        name:
          type: string
        displayName:
          type: string
        description:
          type: string
        meta:
          $ref: '#/components/schemas/CategoryMeta'
        tagsAllowed:
          uniqueItems: true
          type: array
          items:
            type: string
    Category1:
      enum:
        - content
        - account
      type: string
    CategoryCreate:
      description: Category creation params
      required:
        - name
        - displayName
        - description
        - meta
      type: object
      properties:
        name:
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
          type: string
        displayName:
          type: string
        description:
          type: string
        meta:
          $ref: '#/components/schemas/CategoryMeta'
        tagsAllowed:
          uniqueItems: true
          type: array
          items:
            type: string
          nullable: true
    CategoryMeta:
      description: Category additional data
      required:
        - color
      type: object
      properties:
        color:
          description: Category color in HEX format
          type: string
          example: '#FF5733'
    CategoryNameCheck:
      description: >-
        Response for checking if a category name (slug) is already in use within
        a forum
      required:
        - exists
      type: object
      properties:
        exists:
          description: Whether the category name already exists in the forum
          type: boolean
          example: true
    CategoryUpdate:
      description: Category update params
      required:
        - name
        - displayName
        - description
        - meta
      type: object
      properties:
        name:
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
          type: string
        displayName:
          type: string
        description:
          type: string
        meta:
          $ref: '#/components/schemas/CategoryMeta'
        tagsAllowed:
          uniqueItems: true
          type: array
          items:
            type: string
          nullable: true
    ChangeUserState:
      description: >-
        Request to change a user's moderation state. Used for suspending,
        limiting, or reactivating user accounts.
      required:
        - newState
        - userId
      type: object
      properties:
        newState:
          description: New moderation state for the user(s).
          type: string
          allOf:
            - $ref: '#/components/schemas/UserState'
          example: SUSPENDED
        reportId:
          description: >-
            Optional report ID if this action is in response to a moderation
            report.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: report_01234567890abcdef
          nullable: true
        reason:
          description: >-
            Optional reason for the state change. Limited to 120 characters.
            Logged in audit trail.
          maxLength: 120
          minLength: 1
          type: string
          example: Violation of community guidelines - spam behavior
          nullable: true
        userId:
          description: User ID to change state for. Must be a valid USER type TypeId.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: user_01234567890abcdef
    ChangeUserStateBase:
      description: Base request for changing user moderation state.
      required:
        - newState
      type: object
      properties:
        newState:
          description: New moderation state for the user(s).
          type: string
          allOf:
            - $ref: '#/components/schemas/UserState'
          example: SUSPENDED
        reportId:
          description: >-
            Optional report ID if this action is in response to a moderation
            report.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: report_01234567890abcdef
          nullable: true
        reason:
          description: >-
            Optional reason for the state change. Limited to 120 characters.
            Logged in audit trail.
          maxLength: 120
          minLength: 1
          type: string
          example: Violation of community guidelines - spam behavior
          nullable: true
    ChangeUserStateBulk:
      description: Request to change moderation state for multiple users in one operation.
      required:
        - newState
        - userIds
      type: object
      properties:
        newState:
          description: New moderation state for the user(s).
          type: string
          allOf:
            - $ref: '#/components/schemas/UserState'
          example: SUSPENDED
        reportId:
          description: >-
            Optional report ID if this action is in response to a moderation
            report.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: report_01234567890abcdef
          nullable: true
        reason:
          description: >-
            Optional reason for the state change. Limited to 120 characters.
            Logged in audit trail.
          maxLength: 120
          minLength: 1
          type: string
          example: Violation of community guidelines - spam behavior
          nullable: true
        userIds:
          description: >-
            List of user IDs to change state for. Must be valid USER TypeIds.
            Maximum 50.
          maxItems: 50
          minItems: 1
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
    ChangeUsersStateResult:
      description: Result of a bulk user state change operation.
      required:
        - totalRequested
        - totalUpdated
        - notFound
      type: object
      properties:
        totalRequested:
          format: int32
          description: Total number of user IDs requested
          type: integer
        totalUpdated:
          format: int32
          description: Total number of users updated in DB
          type: integer
        notFound:
          description: User IDs that were not found or already deleted
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
    ChangeVideoThumbnail:
      description: Change video thumbnail request. Contains the time in seconds.
      type: object
      properties:
        time:
          format: double
          type: number
    Choice:
      description: >-
        A selectable option for single-choice or multiple-choice questions. Each
        choice has display text and an order value for consistent presentation.
      required:
        - text
        - order
      type: object
      properties:
        text:
          description: The display text for this choice option (max 60 characters)
          maxLength: 60
          pattern: \S
          type: string
          example: I want to learn from others
        order:
          format: int32
          description: Display order for this choice (lower values appear first)
          minimum: 0
          type: integer
          example: 0
    CodeVerificationParams:
      description: Params to verify email or phone number
      required:
        - hash
        - code
      type: object
      properties:
        hash:
          description: Registration hash
          pattern: \S
          type: string
          example: aaaaaaa-ccccccccccccc-wwwwwwwww
        code:
          format: int32
          description: Confirmation code
          type: integer
          example: 854882
    ConfigureRequest:
      required:
        - url
      type: object
      properties:
        url:
          description: >-
            Base URL of the remote link provider (must include http:// or
            https://)
          type: string
          example: https://link.example.com
    CountryInfo:
      required:
        - flags
        - name
        - idd
      type: object
      properties:
        flags:
          $ref: '#/components/schemas/Flags'
        name:
          $ref: '#/components/schemas/Name'
        idd:
          $ref: '#/components/schemas/Idd'
    CreateDraftRequest:
      required:
        - text
      type: object
      properties:
        text:
          pattern: \S
          type: string
        ownerId:
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        title:
          type: string
          nullable: true
        privacy:
          allOf:
            - $ref: '#/components/schemas/PostPrivacy'
          nullable: true
        tags:
          type: array
          items:
            type: string
          nullable: true
        postId:
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        postAsOwner:
          type: boolean
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
          nullable: true
    CreateEvent:
      description: Event params for creating new event
      required:
        - name
        - startTime
        - ianaTimeZone
        - status
        - privacy
      type: object
      properties:
        groupId:
          description: Group id, not required for personal events
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        name:
          description: Event name
          type: string
          example: New Event Name
        startTime:
          description: Event start time in UTC
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2024-02-18T15:00:00Z'
        endTime:
          description: Event end time in UTC
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2024-02-18T18:00:00Z'
          nullable: true
        ianaTimeZone:
          description: Event IANA time zone name
          type: string
          example: Europe/Paris
        description:
          description: Event's description
          type: string
          example: This is a birthday party
          nullable: true
        url:
          format: uri
          description: Event URL
          type: string
          nullable: true
        address:
          description: Event address
          type: object
          allOf:
            - $ref: '#/components/schemas/AddressData'
          nullable: true
        imageId:
          description: Event cover image
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        status:
          description: Event status
          type: string
          allOf:
            - $ref: '#/components/schemas/EventStatus'
          example: CONFIRMED
        privacy:
          description: Event visibility
          type: string
          allOf:
            - $ref: '#/components/schemas/PostPrivacy'
          example: PUBLIC
        invitees:
          description: Users to invite to a private event
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
          nullable: true
    CreatePost:
      description: Post creation params
      required:
        - text
        - privacy
        - kind
      type: object
      properties:
        text:
          description: Post text
          type: string
          example: Hello World
        privacy:
          description: Post privacy
          type: string
          allOf:
            - $ref: '#/components/schemas/PostPrivacy'
          example: PUBLIC
        kind:
          description: Note or Article
          type: string
          allOf:
            - $ref: '#/components/schemas/PostKind'
          example: Note
        attachments:
          description: List with upload ids of attachments
          maxItems: 256
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
          nullable: true
        poll:
          description: Poll parameters
          type: object
          allOf:
            - $ref: '#/components/schemas/PollCreate'
          nullable: true
        commentsEnabled:
          description: Enable/disable comments for the post
          type: boolean
        sensitive:
          description: >-
            Mark status and attached media as sensitive. contentWarning should
            be provided when this flag is true. Defaults to false.
          type: boolean
        contentWarning:
          description: >-
            Content warning. The post content and media will be hidden under the
            warning.
          type: string
          nullable: true
        ownerId:
          description: >-
            Null if regular post. category_id for Categories (Forum) and
            event_id for events
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        title:
          description: Title of a post in forum
          type: string
          nullable: true
        tags:
          description: >-
            List of tags. The other way to add tags is using '#' hashtags in
            text
          type: array
          items:
            type: string
          nullable: true
        withPreview:
          description: Create Preview Card for for link in the post
          type: boolean
        mediaType:
          description: >-
            Post media type. Default for Note is text/plain, for Article
            text/markdown
          type: string
          allOf:
            - $ref: '#/components/schemas/PostMediaType'
          nullable: true
        imageUploadId:
          description: >-
            Upload ID for the article image (will also be included in
            attachments)
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        postAsOwner:
          description: >-
            When true, the post is attributed to the group channel specified by
            ownerId. Only available to channel moderators/admins and only for
            top-level posts.
          type: boolean
    CreateReport:
      required:
        - comment
        - targetPostIds
      type: object
      properties:
        comment:
          type: string
        targetUserId:
          description: User who is being reported
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: us_01hz1frg9sf48d7a8sn2kdr8w3h
          nullable: true
        targetPostIds:
          description: Posts that are being reported
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
          example:
            - pt_01hz1f0jkdw3h27a2kdr8sn2kt
        forward:
          type: boolean
    CreateUpload:
      description: Create upload request
      required:
        - extension
        - tags
      type: object
      properties:
        extension:
          type: string
        isGzipped:
          type: boolean
        meta:
          description: User meta attached to upload. Can contain information like name etc.
          type: object
          allOf:
            - $ref: '#/components/schemas/Meta'
          example:
            name: value
          nullable: true
        tags:
          description: Tags attached to the upload
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/UploadsTags'
          example:
            - $post
            - $avatar
        privacy:
          description: 'Privacy of the upload. Possible values: PUBLIC, PRIVATE, DIRECT.'
          type: string
          allOf:
            - $ref: '#/components/schemas/UploadPrivacy'
          example: PUBLIC
          nullable: true
        allowedUsers:
          description: |2-

                    Can contain a list of users who are allowed to access the upload.
                    Works only for uploads with privacy set to DIRECT.
                    
          uniqueItems: true
          type: array
          items:
            type: string
          nullable: true
    CreateUploadFromRemote:
      description: Create upload from remote request
      required:
        - originalFile
        - otherFiles
        - tags
      type: object
      properties:
        originalFile:
          $ref: '#/components/schemas/RemoteFileInfo'
        otherFiles:
          type: array
          items:
            $ref: '#/components/schemas/RemoteFileInfo'
        meta:
          description: Can contain any meta information about the upload
          type: object
          additionalProperties: {}
          nullable: true
        tags:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/UploadsTags'
    CreateUploadResult:
      description: >-
        Result of creating an upload. Contains the upload URI and the upload
        object.
      required:
        - uri
        - upload
      type: object
      properties:
        uri:
          format: uri
          type: string
        upload:
          $ref: '#/components/schemas/Upload'
    DataCreate:
      required:
        - ownerId
        - type
        - data
      type: object
      properties:
        ownerId:
          description: >-
            Owner identifier of the data. Can be a user ID, group ID,
            user-in-group format userId:groupId, or 'platform'
          type: string
          example: usr_01hq8c8em5hj1vr2f4h1t9db9q
        type:
          description: Type identifier for categorizing the data
          type: string
          example: user_profile
        tags:
          description: Optional list of tags for additional categorization
          type: array
          items:
            type: string
          example:
            - personal
            - profile
          nullable: true
        data:
          description: JSON string containing the actual data payload
          type: string
          example: '{"name": "John Doe", "bio": "Developer"}'
    DeleteUploadResponse:
      description: Delete upload response
      required:
        - id
      type: object
      properties:
        id:
          description: ID of deleted upload
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
    DeviceKeys:
      required:
        - p256dh
        - auth
      type: object
      properties:
        p256dh:
          type: string
        auth:
          type: string
    DeviceRegistrationRequest:
      required:
        - deviceId
        - fcmToken
        - endpoint
        - keys
        - platform
      type: object
      properties:
        deviceId:
          type: string
        fcmToken:
          type: string
        endpoint:
          type: string
        keys:
          $ref: '#/components/schemas/DeviceKeys'
        platform:
          type: string
        device:
          type: string
          nullable: true
    DomainBlockState:
      description: |2-

            Registration mode:
              * SUSPEND - removes all content, media, and profile data for this domain's accounts from your server.
              * LIMIT - makes posts from accounts at this domain invisible to anyone who isn't following them.
              * NOOP - when you just want to reject media files or reports.
               
      enum:
        - SUSPEND
        - LIMIT
        - NOOP
      type: string
    DomainBlocksAccess:
      enum:
        - NONE
        - USER
        - ALL
      type: string
    Draft:
      required:
        - id
        - userId
        - text
        - ownerId
        - ownerType
        - local
        - privacy
        - tags
        - createdAt
        - updatedAt
        - attachments
        - postAsOwner
      type: object
      properties:
        id:
          description: internal draft id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        userId:
          description: ID of the user who owns this draft
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        text:
          description: Draft text
          type: string
        ownerId:
          description: >-
            ID of the entity this draft is for (user channel, forum category or
            event)
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        ownerType:
          description: 'Post owner type that determines routing: USER, CATEGORY or EVENT'
          type: string
          allOf:
            - $ref: '#/components/schemas/PostOwnerType'
        title:
          description: Optional title for forum/article drafts
          type: string
          nullable: true
        local:
          description: Whether the draft is local to this server
          type: boolean
        privacy:
          description: Draft privacy level for the resulting post
          type: string
          allOf:
            - $ref: '#/components/schemas/PostPrivacy'
          example: PUBLIC
        tags:
          description: List of tags associated with the draft
          type: array
          items:
            type: string
        postId:
          description: If this draft edits an existing post, its ID
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        createdAt:
          description: When the draft was created
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
        updatedAt:
          description: When the draft was last updated
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
        attachments:
          description: Upload IDs attached to this draft
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
        postAsOwner:
          description: Post as owner
          type: boolean
    Duration:
      format: double
      description: Duration in seconds
      type: number
      example: '3600'
    EPData:
      description: Employer Profile data
      required:
        - name
        - industry
        - size
      type: object
      properties:
        name:
          description: The name of the company/firm
          maxLength: 256
          type: string
          nullable: true
        industry:
          description: The industry
          maxLength: 128
          type: string
          nullable: true
        size:
          format: int32
          description: The number of employees
          maximum: 100000000
          minimum: 1
          type: integer
          nullable: true
        yearFounded:
          format: int32
          description: The year of the company foundation
          maximum: 2050
          minimum: 999
          type: integer
          nullable: true
        website:
          description: The company's website
          maxLength: 256
          pattern: ^(https?|ftp)://[^\s/$.?#].[^\s]*$
          type: string
          nullable: true
        description:
          description: The company's free text description
          maxLength: 9184
          type: string
          nullable: true
        specialties:
          description: The list of company specialties
          maxItems: 128
          type: array
          items:
            type: string
          nullable: true
        location:
          description: The company's location/address
          type: object
          allOf:
            - $ref: '#/components/schemas/EPLocation'
          nullable: true
    EPLocation:
      description: Employer Profile location
      required:
        - city
        - stateProvince
        - country
        - timezone
        - postcode
      type: object
      properties:
        city:
          description: The company's home city/town
          maxLength: 256
          type: string
          nullable: true
        stateProvince:
          description: The company's state/province/region
          maxLength: 256
          type: string
          nullable: true
        country:
          description: The company's country
          maxLength: 256
          type: string
          nullable: true
        timezone:
          description: The company's time zone
          maxLength: 32
          type: string
          nullable: true
        postcode:
          description: The company's postal code
          maxLength: 64
          type: string
          nullable: true
    Ed25519PublicKey:
      required:
        - key
        - encoded
      type: object
      properties:
        key:
          $ref: '#/components/schemas/Ed25519PublicKeyParameters'
        encoded:
          format: binary
          type: string
    Ed25519PublicKeyParameters:
      type: object
      properties:
        privateKey:
          type: boolean
        private:
          type: boolean
        publicPoint:
          $ref: '#/components/schemas/PublicPoint'
        encoded:
          format: binary
          type: string
    EmailBlock:
      description: Represents a blocked email pattern used to prevent signups
      required:
        - pattern
        - reason
        - createdAt
      type: object
      properties:
        pattern:
          description: >-
            The normalized email pattern that is blocked. Can be a specific
            email or a domain
          type: string
          example: spam-domain.com
        reason:
          description: The reason why this email pattern was blocked
          type: string
          example: Known spam domain
        createdAt:
          description: Timestamp when the email block was created
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2024-01-15T10:30:00Z'
    EmailChangeRequest:
      description: Params to change account email
      required:
        - newEmail
        - password
      type: object
      properties:
        newEmail:
          description: New email
          type: string
          example: john_smith@gmail.com
        password:
          description: Current account password
          maxLength: 64
          minLength: 1
          type: string
          example: PassW0rd!
    Emoji:
      required:
        - shortcode
        - url
        - staticUrl
      type: object
      properties:
        shortcode:
          type: string
        category:
          type: string
          nullable: true
        url:
          format: uri
          type: string
        staticUrl:
          type: string
        visibleInPicker:
          type: boolean
    EmojiPaginatedResponse:
      required:
        - items
      type: object
      properties:
        items:
          description: Paginated list of emojis for the current page
          type: array
          items:
            $ref: '#/components/schemas/Emoji'
        total:
          format: int32
          description: Total number of emojis that satisfy the filter
          type: integer
        totalItems:
          format: int32
          description: Total number of all emojis in the system
          type: integer
    EmojiPatchRequest:
      type: object
      properties:
        category:
          description: New category for the emoji
          type: string
          nullable: true
        visibleInPicker:
          description: Visibility in emoji picker
          type: boolean
          nullable: true
        domain:
          description: Domain for federated emoji metadata
          type: string
          nullable: true
    EmployeeProfile:
      description: The profile of the employee
      required:
        - profileId
        - cpData
      type: object
      properties:
        profileId:
          description: Internal Employer Profile id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        current:
          description: Flag marking the 'current' profile
          type: boolean
        cpData:
          description: Employee Profile data
          type: object
          allOf:
            - $ref: '#/components/schemas/CPData'
    EmployerProfile:
      description: The profile of the employer
      required:
        - profileId
        - EPData
      type: object
      properties:
        profileId:
          description: internal Employer Profile id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        current:
          description: Flag marking the 'current' profile
          type: boolean
        EPData:
          description: Employer Profile data
          type: object
          allOf:
            - $ref: '#/components/schemas/EPData'
    EntryPoint:
      enum:
        - GLOBAL
        - USER
        - GROUP
      type: string
    Event:
      description: User's Event
      required:
        - id
        - uri
        - groupId
        - name
        - startTime
        - timeZoneOffsetSeconds
        - stats
        - status
        - privacy
        - createdAt
        - updatedAt
        - organizer
      type: object
      properties:
        id:
          description: Internal event id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        uri:
          format: uri
          description: Unique event uri
          type: string
        groupId:
          description: Group id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        name:
          description: Event's name
          type: string
        startTime:
          description: Event's start time
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
        endTime:
          description: Event's end time
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        ianaTimeZone:
          description: Event's IANA time zone
          type: string
          nullable: true
        timeZoneOffsetSeconds:
          format: int32
          description: Event's time zone offset (in seconds)
          type: integer
        description:
          description: Event's Markdown description (absent for non-local events)
          type: string
          nullable: true
        descriptionHtml:
          description: Event's HTML description
          type: string
          nullable: true
        url:
          format: uri
          description: Event's virtual location URL
          type: string
          nullable: true
        addressId:
          format: int32
          description: Event's address id
          type: integer
          nullable: true
        tags:
          description: Event's tags
          type: array
          items:
            type: string
          nullable: true
        mentions:
          description: Event's mentions
          type: array
          items:
            format: uri
            type: string
          nullable: true
        stats:
          description: Stats
          type: object
          allOf:
            - $ref: '#/components/schemas/EventStats'
        status:
          description: Event status
          type: string
          allOf:
            - $ref: '#/components/schemas/EventStatus'
          example: CONFIRMED
        attendeeStatus:
          description: Viewer user's event attendance status
          type: string
          allOf:
            - $ref: '#/components/schemas/EventAttendeeStatus'
          example: INVITED
          nullable: true
        commentCount:
          format: int32
          description: Event comment count
          type: integer
          nullable: true
        privacy:
          $ref: '#/components/schemas/PostPrivacy'
        translation:
          allOf:
            - $ref: '#/components/schemas/EventTranslation'
          nullable: true
        createdAt:
          $ref: '#/components/schemas/Instant'
        updatedAt:
          $ref: '#/components/schemas/Instant'
        deletedAt:
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        lang:
          allOf:
            - $ref: '#/components/schemas/Language'
          nullable: true
        organizer:
          $ref: '#/components/schemas/User'
        cover:
          allOf:
            - $ref: '#/components/schemas/Upload'
          nullable: true
        address:
          allOf:
            - $ref: '#/components/schemas/AddressData'
          nullable: true
        emojis:
          type: array
          items:
            $ref: '#/components/schemas/Emoji'
          nullable: true
    EventAttendee:
      description: Event attendee status
      required:
        - uri
        - status
      type: object
      properties:
        user:
          allOf:
            - $ref: '#/components/schemas/User'
          nullable: true
        uri:
          format: uri
          type: string
        status:
          $ref: '#/components/schemas/EventAttendeeStatus'
    EventAttendeeStatus:
      description: |2-

                Event attendee statuses

                * INVITED - a user has been invited to an event (for private events only).
                * JOINED - a user has joined and thus attending an event.
                * JOINED_TENTATIVELY - a user has tentatively joined / show an interest in an event.
                * REJECTED - a user has rejected an event invitation, and won't attend an event (for private events only).
            
      enum:
        - INVITED
        - JOINED
        - JOINED_TENTATIVELY
        - REJECTED
      type: string
    EventStats:
      type: object
      properties:
        interests:
          format: int32
          type: integer
        joins:
          format: int32
          type: integer
    EventStatus:
      description: Event's status
      enum:
        - CONFIRMED
        - CANCELLED
      type: string
    EventTranslation:
      description: Event translation
      required:
        - name
      type: object
      properties:
        name:
          type: string
        descriptionHtml:
          type: string
          nullable: true
    EventsSettings:
      description: Events app settings
      required:
        - ownerId
        - exportPublicCalendar
        - exportPublicDetails
        - exportPublicEvents
        - exportPrivateCalendar
        - exportPrivateEvents
      type: object
      properties:
        ownerId:
          description: Owner ID
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        exportPublicCalendar:
          description: Enable public calendar export
          type: boolean
        exportPublicDetails:
          description: Enable public calendar export with full event details
          type: boolean
        exportPublicEvents:
          description: Events to export in public calendar
          type: string
          allOf:
            - $ref: '#/components/schemas/ExportCalendarEvents'
        exportPrivateCalendar:
          description: Enable private calendar export
          type: boolean
        exportPrivateEvents:
          description: Events to export in private calendar
          type: string
          allOf:
            - $ref: '#/components/schemas/ExportCalendarEvents'
        exportPrivateCalendarUniqueId:
          description: Private calendar unique id
          type: string
          nullable: true
    Executor:
      type: object
      properties:
        accountId:
          description: ID of the account that performed the action
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: ac_01hxcvk1hjexere4pvtrj0ymqq
          nullable: true
        userId:
          description: ID of the user that performed the action
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        email:
          description: Email of the account that performed the action
          type: string
          example: john@example.com
          nullable: true
        username:
          description: Username of the user that performed the action
          type: string
          example: john_smith
          nullable: true
        serviceName:
          description: Name of the service that performed the action
          type: string
          example: system
          nullable: true
    ExportCalendarEvents:
      description: |2-

                Events to export.

                * OWN - export own events only (the only option for groups).
                * JOINED - export own and joined events (not applicable to groups).
                * INTERESTED - export own, joined and events user is interested in (not applicable to groups).
            
      enum:
        - OWN
        - JOINED
        - INTERESTED
      type: string
    FeedCompareResult:
      required:
        - redisIds
        - dbIds
        - onlyInRedis
        - onlyInDb
      type: object
      properties:
        redisIds:
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
        dbIds:
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
        onlyInRedis:
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
        onlyInDb:
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
        orderMismatch:
          type: boolean
        matchesExact:
          type: boolean
        redisCount:
          format: int32
          type: integer
        dbCount:
          format: int32
          type: integer
    FeedMetrics:
      required:
        - op
        - ts
      type: object
      properties:
        time:
          format: int64
          type: integer
        count:
          format: int32
          type: integer
        op:
          $ref: '#/components/schemas/FeedOperation'
        ts:
          $ref: '#/components/schemas/Instant'
    FeedOperation:
      enum:
        - populate
        - merge
        - unmerge
        - redis
        - redisLex
        - cache
        - idsDb
        - db
        - add
        - remove
      type: string
    FileDesc:
      description: File of the upload
      required:
        - uri
        - fileId
        - extension
        - original
        - meta
        - size
        - createdAt
        - updatedAt
        - type
      type: object
      properties:
        uri:
          description: Full url of the file
          type: string
          nullable: true
        fileId:
          description: File id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        extension:
          description: File extension
          type: string
          example: mp4
        original:
          description: true if this file is original, false if it is a derivative
          type: boolean
        meta:
          description: File metadata. Contains optional values for width, height etc.
          type: object
          allOf:
            - $ref: '#/components/schemas/Meta1'
        size:
          format: int64
          description: File size in bytes
          type: integer
        createdAt:
          $ref: '#/components/schemas/Instant'
        updatedAt:
          $ref: '#/components/schemas/Instant'
        type:
          description: File type
          type: string
          allOf:
            - $ref: '#/components/schemas/UploadType'
          example: VIDEO
    FileExtension:
      description: File extension
      type: string
      example: mp4
    FinishCreatingAccountParams:
      description: Finish creating account with an option to change username
      required:
        - hash
      type: object
      properties:
        hash:
          description: Registration hash
          pattern: \S
          type: string
          example: aaaaaaa-ccccccccccccc-wwwwwwwww
        username:
          description: Another username
          type: string
          nullable: true
    Flags:
      required:
        - png
        - svg
        - alt
      type: object
      properties:
        png:
          type: string
        svg:
          type: string
        alt:
          type: string
    FollowResult:
      required:
        - result
      type: object
      properties:
        result:
          type: string
    FollowingStatus:
      enum:
        - PENDING
        - ACCEPTED
        - REJECTED
      type: string
    Forum:
      description: Forum representation for API responses
      required:
        - id
        - policy
        - meta
        - createdAt
        - updatedAt
        - ownerId
      type: object
      properties:
        id:
          description: internal forum id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        policy:
          description: forum policy settings
          type: object
          allOf:
            - $ref: '#/components/schemas/ForumPolicy'
        meta:
          description: additional forum metadata
          type: object
          allOf:
            - $ref: '#/components/schemas/ForumMeta'
        createdAt:
          description: when the forum was created
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
        updatedAt:
          description: when the forum was last updated
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
        ownerId:
          description: ID of the group that owns this forum
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
    ForumMeta:
      type: object
      properties:
        dummy:
          type: string
          nullable: true
    ForumPolicy:
      type: object
      properties:
        dummy:
          type: string
          nullable: true
    ForumStats:
      type: object
      properties:
        categories:
          format: int64
          type: integer
        tags:
          format: int64
          type: integer
    ForumUpdate:
      description: Forum creation params
      required:
        - policy
        - meta
      type: object
      properties:
        policy:
          $ref: '#/components/schemas/ForumPolicy'
        meta:
          $ref: '#/components/schemas/ForumMeta'
    Geo:
      description: Coordinates and other geo data
      type: object
      properties:
        latitude:
          format: double
          type: number
        longitude:
          format: double
          type: number
        altitude:
          format: double
          type: number
          nullable: true
        accuracy:
          format: double
          type: number
          nullable: true
        verticalAccuracy:
          format: double
          type: number
          nullable: true
        speed:
          format: double
          type: number
          nullable: true
        bearing:
          format: double
          type: number
          nullable: true
        timestamp:
          format: int64
          type: integer
          nullable: true
    GeoData:
      description: >-
        Geographic location data including country, city, and timezone
        information
      type: object
      properties:
        countryCode:
          description: ISO country code
          type: string
          nullable: true
        country:
          description: Country name
          type: string
          nullable: true
        subdivision:
          description: Subdivision or state/province name
          type: string
          nullable: true
        city:
          description: City name
          type: string
          nullable: true
        timeZone:
          description: IANA timezone identifier
          type: string
          nullable: true
    GlobalAggregatedMetrics:
      required:
        - lastUpdated
        - operation
      type: object
      properties:
        globalAverage:
          format: double
          type: number
        totalMeasurements:
          format: int64
          type: integer
        totalTime:
          format: int64
          type: integer
        userCount:
          format: int64
          type: integer
        lastUpdated:
          $ref: '#/components/schemas/Instant'
        operation:
          $ref: '#/components/schemas/FeedOperation'
        ownerType:
          allOf:
            - $ref: '#/components/schemas/PostOwnerType'
          nullable: true
    Group:
      description: Detailed information about a group including internal data
      required:
        - meta
        - privacy
        - visibility
        - joinMode
        - groupId
        - groupName
        - domain
        - displayName
        - summary
        - uri
        - publicKey
        - stats
        - fields
        - type
        - membersUrl
        - createdAt
        - updatedAt
      type: object
      properties:
        meta:
          description: group metadata including color
          type: object
          allOf:
            - $ref: '#/components/schemas/GroupMeta'
        privacy:
          description: who can access the group's content
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupPrivacy'
        visibility:
          description: how discoverable the group is
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupVisibility'
        joinMode:
          description: how users can join the group
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupJoinMode'
        location:
          description: group's location
          type: object
          allOf:
            - $ref: '#/components/schemas/Location'
          nullable: true
        timezone:
          description: group's timezone
          type: object
          allOf:
            - $ref: '#/components/schemas/TimeZone'
          nullable: true
        groupId:
          description: internal id of this group
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        groupName:
          description: unique group name
          type: string
        domain:
          description: group's domain, remote only, empty for local
          type: string
        displayName:
          description: full name of the group
          type: string
        summary:
          description: Group description
          type: string
        uri:
          format: uri
          description: URI of this group
          type: string
        publicKey:
          description: Group's public key for ActivityPub
          type: string
        privateKey:
          description: Group's private key for ActivityPub
          type: string
          nullable: true
        forumId:
          description: ID of the forum associated with this group
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        stats:
          description: Group statistics
          type: object
          additionalProperties: {}
        fields:
          description: Custom fields for the group
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UserField'
        type:
          description: the type of this group
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupType'
        membersUrl:
          description: URL to group members
          type: string
        banner:
          description: Group's header/banner upload
          type: object
          allOf:
            - $ref: '#/components/schemas/Upload'
          nullable: true
        avatar:
          description: Group's avatar
          type: object
          allOf:
            - $ref: '#/components/schemas/Upload'
          nullable: true
        deletedAt:
          description: Group deletion timestamp
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        createdAt:
          description: Group's creation timestamp
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
        updatedAt:
          description: Group's last update timestamp
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
        membersCount:
          format: int32
          description: Cached count of active members in the group
          type: integer
    GroupBrandingUpdate:
      description: >-
        Request payload for updating a group's visual branding elements. All
        fields are optional - only provide the fields you want to update.
        Setting image fields to null removes them.
      required:
        - color
      type: object
      properties:
        color:
          description: >-
            Theme color for the group in 6-character HEX format with # prefix.
            Used for UI theming.
          pattern: ^#[0-9A-Fa-f]{6}$
          type: string
          example: '#FF5733'
        bannerId:
          description: >-
            Upload ID of the banner image. Must be a previously uploaded image.
            Set to null to remove the banner.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: up_01hz1f0kw36f82k9s4nzpc4s92n
          nullable: true
        avatarId:
          description: >-
            Upload ID of the avatar image. Must be a previously uploaded image.
            Set to null to remove the avatar.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: up_01hz1f0kw36f82k9s4nzpc4s92n
          nullable: true
    GroupChannelCreateRequest:
      description: >-
        Request payload for creating a new channel within a group. Channels are
        specialized users that enable organized content distribution within
        groups. They support both public and private visibility, with automatic
        constraints based on the parent group's privacy settings.
      required:
        - username
        - displayName
        - summary
        - privacy
      type: object
      properties:
        username:
          description: >-
            Channel identifier scoped to the group. Must be unique within the
            group. Used to generate the channel's username in format
            'groupname:channelname' for private channels.
          pattern: \S
          type: string
          example: news
        displayName:
          description: >-
            Human-readable display name for the channel. Shown in channel
            listings and UI.
          pattern: \S
          type: string
          example: Group News
        summary:
          description: >-
            Brief description of the channel's purpose and content (max 1024
            characters)
          maxLength: 1024
          type: string
          example: Read group news and announcements here
        privacy:
          description: >-
            Channel privacy level. PUBLIC channels are visible to everyone,
            PRIVATE channels only to group members. Private groups can only have
            private channels.
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupChannelPrivacy'
          example: PUBLIC
        isMain:
          description: >-
            Whether this channel should be the main channel for the group. Only
            one main channel allowed per group. The first channel created is
            automatically made main.
          default: false
          type: boolean
          example: false
        isDefault:
          description: >-
            Whether this channel should be a default channel. Default channels
            are automatically followed by new group members. The first channel
            created is automatically made default.
          default: false
          type: boolean
          example: true
        globalUsername:
          description: >-
            Global username for public channels. Must be unique across the
            entire platform. Allows the channel to be accessed via
            '@globalUsername' in addition to the scoped username. Only available
            for public channels in public groups.
          type: string
          example: platform-news
          nullable: true
    GroupChannelPrivacy:
      description: |2-

              * PUBLIC - Channel is visible to everyone and can be followed by anyone.
              * PRIVATE - Channel is visible only to group members and can only be followed by group members.
               
      enum:
        - PUBLIC
        - PRIVATE
      type: string
    GroupChannelUpdateRequest:
      description: >-
        Request payload for updating an existing group channel. Only include
        fields that need to be modified. Null fields are ignored, preserving
        existing values. Changes to privacy settings are constrained by the
        parent group's privacy level.
      type: object
      properties:
        displayName:
          description: >-
            New display name for the channel. Updates how the channel appears in
            UI.
          type: string
          example: Group Announcements
          nullable: true
        summary:
          description: New channel description (max 1024 characters)
          maxLength: 1024
          type: string
          example: Important announcements and updates
          nullable: true
        privacy:
          description: >-
            New privacy level. Cannot make a channel public if the parent group
            is private. Changing from public to private affects visibility and
            access.
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupChannelPrivacy'
          example: PRIVATE
          nullable: true
        isDefault:
          description: >-
            Whether this channel should be a default channel (auto-followed by
            new members)
          type: boolean
          example: true
          nullable: true
        avatarId:
          description: >-
            Upload ID for the channel avatar image. Must be a previously
            uploaded image. Set to null to remove the avatar.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        headerId:
          description: >-
            Upload ID for the channel header/banner image. Must be a previously
            uploaded image. Set to null to remove the header.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        fields:
          description: Channel profile fields (key-value pairs for additional information)
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UserField'
          nullable: true
        location:
          description: Channel location information
          type: object
          allOf:
            - $ref: '#/components/schemas/Location'
          nullable: true
        timezone:
          description: Channel timezone preferences
          type: object
          allOf:
            - $ref: '#/components/schemas/TimeZone'
          nullable: true
    GroupCreate:
      description: |2-

                Request payload for creating a new group. Contains the minimum required information to establish
                a group with default settings. Additional configuration can be done through update endpoints.
            
      required:
        - privacy
        - visibility
        - joinMode
        - name
        - displayName
        - fields
        - meta
        - type
      type: object
      properties:
        privacy:
          description: who can access the group's content
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupPrivacy'
        visibility:
          description: how discoverable the group is
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupVisibility'
        joinMode:
          description: how users can join the group
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupJoinMode'
        bannerId:
          description: Banner upload id or null to remove
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        avatarId:
          description: Avatar upload id or null to remove
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        location:
          description: group's location
          type: object
          allOf:
            - $ref: '#/components/schemas/Location'
          nullable: true
        timezone:
          description: group's timezone
          type: object
          allOf:
            - $ref: '#/components/schemas/TimeZone'
          nullable: true
        name:
          description: >-
            Unique group name used in URLs. Must be alphanumeric with
            underscores/hyphens, 3-30 characters.
          type: string
        displayName:
          description: >-
            Human-readable display name for the group. Can contain spaces and
            special characters.
          type: string
        description:
          description: >-
            Detailed description of the group's purpose and activities. Supports
            markdown formatting.
          type: string
          nullable: true
        fields:
          description: Custom fields for the group
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UserField'
        meta:
          description: >-
            Additional metadata for the group including rules, guidelines, and
            custom fields
          type: object
          allOf:
            - $ref: '#/components/schemas/GroupMeta'
        type:
          description: >-
            The type/category of the group (ORGANIZATION, COMMUNITY, PROJECT,
            etc.)
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupType'
    GroupJoinMode:
      description: |2-

              * OPEN - Anyone can join the group immediately without approval.
              * APPROVAL - User requests must be approved by a group admin or moderator.
              * INVITE_ONLY - Only users with an invitation from a member can join.
               
      enum:
        - OPEN
        - APPROVAL
        - INVITE_ONLY
      type: string
    GroupJoinRequest:
      description: |2-

                A group join request with user information.
                Requests can have status: PENDING (awaiting decision), APPROVED (accepted), or REJECTED (denied).
            
      required:
        - groupJoinRequestId
        - userId
        - groupId
        - username
        - userDisplayName
        - status
        - createdAt
        - updatedAt
      type: object
      properties:
        groupJoinRequestId:
          description: Unique identifier for this group join request
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        userId:
          description: ID of the user requesting to join
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        groupId:
          description: ID of the group being requested to join
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        username:
          description: Username of the user requesting to join
          pattern: \S
          type: string
        userDisplayName:
          description: Display name of the user requesting to join
          pattern: \S
          type: string
        avatarId:
          description: Avatar upload ID of the user
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        answerToken:
          description: >-
            Answer token from completing group questions (if questions were
            required)
          type: string
          nullable: true
        status:
          description: Current status of the join request
          enum:
            - PENDING
            - APPROVED
            - REJECTED
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupJoinRequestStatus'
          example: PENDING
        reason:
          description: Reason provided for approval or rejection
          type: string
          example: Approved - meets community guidelines
          nullable: true
        createdAt:
          description: When the join request was created
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2025-09-17T12:43:53.395287Z'
        updatedAt:
          description: When the join request was last updated (status change, etc)
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2025-09-17T12:43:53.395287Z'
    GroupJoinRequestStatus:
      description: |2-

              * PENDING - Request is pending awaiting approval or rejection by group admin.
              * APPROVED - Request is approved by group admin.
              * REJECTED - Request is rejected by group admin.
            
      enum:
        - PENDING
        - APPROVED
        - REJECTED
      type: string
    GroupJoinRequestsListResponse:
      description: |2-

                Response object for listing group join requests with pagination support and filtering.
                Includes both filtered results and total counts (with and without filters).
            
      required:
        - requests
        - grandTotal
        - total
      type: object
      properties:
        requests:
          description: Array of group join request objects
          type: array
          items:
            $ref: '#/components/schemas/GroupJoinRequest'
        grandTotal:
          format: int32
          description: >-
            Total number of join requests for the specified group (no filters
            applied)
          type: integer
        total:
          format: int32
          description: Total number of join requests matching the applied filters
          type: integer
    GroupMember:
      description: |2-

               Represents a user's membership in a group, including their role, status, and associated metadata.
               This object links a user to a group and defines their permissions and participation level.
            
      required:
        - groupName
        - groupDisplayName
        - userName
        - userDisplayName
        - groupId
        - memberId
        - status
      type: object
      properties:
        groupName:
          description: Group name
          type: string
        groupDisplayName:
          description: Group display name
          type: string
        userName:
          description: User name (username)
          type: string
        userDisplayName:
          description: User display name
          type: string
        userDomain:
          description: User domain (null for local users)
          type: string
          nullable: true
        groupAvatar:
          description: Group avatar upload object
          type: object
          allOf:
            - $ref: '#/components/schemas/Upload'
          nullable: true
        userAvatar:
          description: User avatar upload object
          type: object
          allOf:
            - $ref: '#/components/schemas/Upload'
          nullable: true
        groupId:
          description: Group ID
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        memberId:
          description: User who is a member of the group
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        role:
          description: |2-

                        The role identifier that determines the member's permissions within the group.
                        Common roles include GROUP_VIEWER, GROUP_EDITOR, GROUP_ADMIN
                    
          type: string
          nullable: true
        meta:
          description: Additional metadata about this membership
          type: object
          allOf:
            - $ref: '#/components/schemas/GroupMemberMeta'
          nullable: true
        status:
          description: Current status of the membership (INVITED, MEMBER, or PENDING)
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupMemberStatus'
        createdAt:
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        updatedAt:
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
    GroupMemberCreate:
      description: |2-

                Request payload for adding a new member to a group. Contains the user to add,
                their initial role, and optional metadata. The groupId is provided in the URL path.
            
      required:
        - memberId
        - status
      type: object
      properties:
        memberId:
          description: User who will be added as a member of the group
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        role:
          description: >-
            The initial role to assign to the new member. Defaults to
            GROUP_VIEWER if not specified
          type: string
          nullable: true
        meta:
          description: Optional metadata to attach to this membership
          type: object
          allOf:
            - $ref: '#/components/schemas/GroupMemberMeta'
          nullable: true
        status:
          description: >-
            Initial status of the membership. Defaults to MEMBER if not
            specified
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupMemberStatus'
    GroupMemberMeta:
      description: >-
        Additional metadata for a group member, such as custom descriptions or
        notes about their membership
      required:
        - description
      type: object
      properties:
        description:
          description: >-
            Optional description or note about this member's role or
            participation in the group
          type: string
    GroupMemberRoleFilter:
      description: |2-

              Role filter for group members:
              * MEMBER - Returns only regular members of the group
              * ADMIN - Returns all non-regular members (any admin role)
               
      enum:
        - MEMBER
        - ADMIN
      type: string
    GroupMemberStatus:
      description: The current status of a user's membership in a group
      enum:
        - INVITED
        - MEMBER
        - PENDING
      type: string
    GroupMemberUpdate:
      description: |2-

                Request payload for updating an existing group member. All fields are optional -
                only provide the fields you want to update.
                Commonly used to change member roles or status.
            
      type: object
      properties:
        role:
          description: >-
            New role to assign to the member. If null, the role remains
            unchanged
          type: string
          nullable: true
        meta:
          description: >-
            Updated metadata for this membership. If null, metadata remains
            unchanged
          type: object
          allOf:
            - $ref: '#/components/schemas/GroupMemberMeta'
          nullable: true
        status:
          description: New status for the membership. If null, status remains unchanged
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupMemberStatus'
          nullable: true
    GroupMembersSortBy:
      description: |2-

              Sort options for group members list:
              * JOIN - Sort by join time
              * POSTS - Sort by number of posts in this group (channels and forums)
              * FOLLOWERS - Sort to show current user's followers first, secondary sort by updated_at
              * FOLLOWING - Sort to show users current user is following first, secondary sort by updated_at
              * RELATIONS - Sort to show users with any relationship (followers or following) first, secondary sort by updated_at
               
      enum:
        - JOIN
        - POSTS
        - FOLLOWERS
        - FOLLOWING
        - RELATIONS
      type: string
    GroupMeta:
      description: Group Details additional data
      required:
        - color
      type: object
      properties:
        color:
          description: Group color in HEX format
          type: string
    GroupPin:
      description: Represents a user's pinned group with ordering information
      required:
        - userId
        - groupId
        - pin
        - createdAt
        - updatedAt
      type: object
      properties:
        userId:
          description: ID of the user who pinned the group
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        groupId:
          description: ID of the pinned group
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        pin:
          format: int32
          description: Pin order number (positive integer for sorting)
          minimum: 0
          type: integer
        createdAt:
          description: When the group was pinned
          type: string
          allOf:
            - $ref: '#/components/schemas/LocalDateTime'
        updatedAt:
          description: When the pin was last updated
          type: string
          allOf:
            - $ref: '#/components/schemas/LocalDateTime'
    GroupPrivacy:
      description: |2-

              * PUBLIC - Open Content. Content and membership are viewable by anyone.
              * PRIVATE - Members-Only Content. Outsiders cannot see posts or members unless they join.
               
      enum:
        - PUBLIC
        - PRIVATE
      type: string
    GroupType:
      enum:
        - CHANNEL
        - INTEREST_GROUP
        - ORGANIZATION
      type: string
    GroupUpdate:
      description: |2-

                Request payload for updating an existing group. All fields reflect the complete new state
                of the group. Changes to privacy settings may affect member access. Name changes update the group's URL.
            
      required:
        - meta
        - privacy
        - visibility
        - joinMode
        - name
        - displayName
        - fields
      type: object
      properties:
        meta:
          description: group metadata including color
          type: object
          allOf:
            - $ref: '#/components/schemas/GroupMeta'
        privacy:
          description: who can access the group's content
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupPrivacy'
        visibility:
          description: how discoverable the group is
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupVisibility'
        joinMode:
          description: how users can join the group
          type: string
          allOf:
            - $ref: '#/components/schemas/GroupJoinMode'
        bannerId:
          description: Banner upload id or null to remove
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        avatarId:
          description: Avatar upload id or null to remove
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        location:
          description: group's location
          type: object
          allOf:
            - $ref: '#/components/schemas/Location'
          nullable: true
        timezone:
          description: group's timezone
          type: object
          allOf:
            - $ref: '#/components/schemas/TimeZone'
          nullable: true
        name:
          description: >-
            New unique group name. This will update the group's URL. Must be
            unique across the platform.
          type: string
        displayName:
          description: >-
            Updated display name for the group. This is what users see in the
            UI.
          type: string
        description:
          description: Updated group description. Set to null to keep existing description.
          type: string
          nullable: true
        fields:
          description: Custom fields for the group; processed like user's fields
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UserField'
    GroupVisibility:
      description: |2-

              * VISIBLE - The group is listed openly. It shows up in search results or directory listings.
              * UNLISTED - The group does not appear in public lists but is accessible via direct link.
              * HIDDEN - The group is completely hidden and invite-only. Shared links will return 404 for non-members.
               
      enum:
        - VISIBLE
        - UNLISTED
        - HIDDEN
      type: string
    GroupnameCheck:
      description: Response for checking if a group name (slug) is already in use
      required:
        - exists
      type: object
      properties:
        exists:
          description: Whether the group name already exists in the database
          type: boolean
          example: true
    Idd:
      required:
        - root
        - suffixes
      type: object
      properties:
        root:
          type: string
        suffixes:
          type: array
          items:
            type: string
    InetAddress:
      type: object
      properties:
        multicastAddress:
          type: boolean
        anyLocalAddress:
          type: boolean
        loopbackAddress:
          type: boolean
        linkLocalAddress:
          type: boolean
        siteLocalAddress:
          type: boolean
        MCGlobal:
          type: boolean
        MCNodeLocal:
          type: boolean
        MCLinkLocal:
          type: boolean
        MCSiteLocal:
          type: boolean
        MCOrgLocal:
          type: boolean
        hostName:
          type: string
        address:
          format: binary
          type: string
        hostAddress:
          type: string
    Instance:
      required:
        - uri
        - title
        - short_description
        - description
        - email
        - version
        - build
        - buildTimestamp
        - urls
        - stats
        - thumbnail
        - languages
        - configuration
        - rules
      type: object
      properties:
        uri:
          description: URI of this instance
          type: string
          example: https://wellesley.social
        title:
          type: string
        short_description:
          type: string
        description:
          type: string
        email:
          type: string
        version:
          description: Version of the platform
          type: string
          example: '1.0'
        build:
          description: 'Build # of the platform'
          type: string
          example: '777'
        buildTimestamp:
          format: int64
          description: Build timestamp
          type: integer
          example: 681486960000
        urls:
          type: object
          additionalProperties:
            type: string
        stats:
          $ref: '#/components/schemas/InstanceStats'
        thumbnail:
          type: string
        languages:
          type: array
          items:
            type: string
        configuration:
          description: This instance configuration
          type: object
          allOf:
            - $ref: '#/components/schemas/InstanceConfiguration'
        contact_account:
          allOf:
            - $ref: '#/components/schemas/User'
          nullable: true
        rules:
          description: List of instance rules
          type: array
          items:
            $ref: '#/components/schemas/Rule'
    InstanceAccess:
      required:
        - visibility
      type: object
      properties:
        visibility:
          description: Whether the server is visible to the public
          enum:
            - PUBLIC
            - PRIVATE
          type: string
    InstanceBranding:
      required:
        - color
        - description
        - displayName
        - image
        - imageThumbnail
        - shortDescription
      type: object
      properties:
        color:
          description: Color theme of the homepage in HEX format
          type: string
        description:
          description: Server description shown on the homepage
          maxLength: 16384
          type: string
        displayName:
          description: Display name shown on the homepage
          type: string
        image:
          description: Image URL shown on the homepage
          type: string
        imageThumbnail:
          description: Thumbnail of the image URL shown on the homepage
          type: string
        shortDescription:
          description: Short description shown on the homepage
          type: string
    InstanceConfiguration:
      required:
        - registrations
        - passwordPolicy
        - access
        - branding
        - domainBlocksPolicy
        - contacts
      type: object
      properties:
        registrations:
          description: Registration configuration
          type: object
          allOf:
            - $ref: '#/components/schemas/InstanceRegistration'
        passwordPolicy:
          description: Password policy configuration
          type: string
          allOf:
            - $ref: '#/components/schemas/PasswordPolicy'
        access:
          description: Access configuration
          type: object
          allOf:
            - $ref: '#/components/schemas/InstanceAccess'
        branding:
          description: Branding configuration
          type: object
          allOf:
            - $ref: '#/components/schemas/InstanceBranding'
        domainBlocksPolicy:
          description: Domain blocks policy configuration
          type: object
          allOf:
            - $ref: '#/components/schemas/InstanceDomainBlocksPolicy'
        contacts:
          description: Instance contacts configuration
          type: object
          allOf:
            - $ref: '#/components/schemas/InstanceContacts'
    InstanceContacts:
      required:
        - email
        - username
      type: object
      properties:
        email:
          description: Contact email for the server
          type: string
        username:
          description: Contact username for the server
          type: string
    InstanceDomainBlocksPolicy:
      required:
        - domainBlocksAccess
        - domainBlocksReasonAccess
      type: object
      properties:
        domainBlocksAccess:
          description: Who can see domains that are blocked by this instance
          enum:
            - NONE
            - USER
            - ALL
          type: string
        domainBlocksReasonAccess:
          description: Who can see reasons for domain blocks by this instance
          enum:
            - NONE
            - USER
            - ALL
          type: string
    InstanceRegistration:
      required:
        - ask_for_info
        - captcha
        - invites
        - message
        - mode
      type: object
      properties:
        ask_for_info:
          description: Whether reason to join should be provided when signing up
          type: boolean
        captcha:
          description: Whether captcha is shown to new users when signing up
          type: boolean
        invites:
          description: Whether existing users can invite other users to join
          type: boolean
        message:
          description: Message shown to guests when registration is closed
          type: string
        mode:
          description: Registration mode on this instance
          enum:
            - OPEN
            - APPROVAL
            - EMAIL_DOMAIN_ALLOWLIST
            - CLOSED
          type: string
          example: OPEN
    InstanceStats:
      required:
        - active30_user_count
        - active180_user_count
      type: object
      properties:
        user_count:
          format: int64
          description: Total number of local users on this day
          type: integer
          nullable: true
        active30_user_count:
          format: int64
          description: Total number of active local users in the last 30 days on this day
          type: integer
          nullable: true
        active180_user_count:
          format: int64
          description: Total number of active local users in the last 180 days on this day
          type: integer
          nullable: true
        group_count:
          format: int64
          description: Total number of local groups on this day
          type: integer
          nullable: true
        post_count:
          format: int64
          description: Local top-level posts created this day
          type: integer
          nullable: true
        post_count_total:
          format: int64
          description: Cumulative local top-level posts up to this day
          type: integer
          nullable: true
        comment_count:
          format: int64
          description: Comments by local users created this day
          type: integer
          nullable: true
        remote_comment_count:
          format: int64
          description: Comments by remote users created this day
          type: integer
          nullable: true
        comment_count_total:
          format: int64
          description: Cumulative comments by local users up to this day
          type: integer
          nullable: true
        remote_comment_count_total:
          format: int64
          description: Cumulative comments by remote users up to this day
          type: integer
          nullable: true
        domain_count:
          format: int64
          description: Total number of external domains on this day
          type: integer
          nullable: true
    InstanceVisibility:
      enum:
        - PUBLIC
        - PRIVATE
      type: string
    Instant:
      format: date-time
      type: string
      example: '2022-03-10T16:15:50Z'
    InviteStatus:
      enum:
        - PENDING
        - ACCEPTED
        - REJECTED
      type: string
    JAAttachment:
      description: Job Application attachment
      required:
        - name
      type: object
      properties:
        name:
          description: The Attachment name
          maxLength: 256
          type: string
        url:
          description: The Attachment's  URL
          maxLength: 256
          pattern: ^(https?|ftp)://[^\s/$.?#].[^\s]*$
          type: string
          nullable: true
        text:
          description: The Attachment text
          maxLength: 10240
          type: string
          nullable: true
    JAData:
      description: Job Application data
      type: object
      properties:
        attachments:
          description: The list of the attachments
          maxItems: 128
          type: array
          items:
            $ref: '#/components/schemas/JAAttachment'
          nullable: true
    JPData:
      description: Job Posting data
      required:
        - title
        - location
        - employmentType
        - jobDescription
        - responsibilities
        - salary
      type: object
      properties:
        title:
          description: The offered title
          maxLength: 256
          type: string
          nullable: true
        location:
          description: The location of the job
          maxLength: 512
          type: string
          nullable: true
        employmentType:
          description: The employment type
          maxLength: 256
          type: string
          example: Full time/Part time/Contract, etc.
          nullable: true
        jobDescription:
          description: The job description
          maxLength: 9184
          type: string
          nullable: true
        responsibilities:
          description: The list of responsibilities
          maxItems: 128
          type: array
          items:
            type: string
          nullable: true
        qualificationsRequired:
          description: The list of required qualifications
          maxItems: 128
          type: array
          items:
            type: string
          nullable: true
        skillsRequired:
          description: The list of required skills
          maxItems: 128
          type: array
          items:
            type: string
          nullable: true
        educationRequired:
          description: The list of required educations
          maxItems: 128
          type: array
          items:
            type: string
          nullable: true
        experienceRequired:
          description: The list of required experiences
          maxItems: 128
          type: array
          items:
            type: string
          nullable: true
        salary:
          description: Monetary compensation offered
          type: object
          allOf:
            - $ref: '#/components/schemas/Salary'
          nullable: true
        benefits:
          description: The list of benefits offered
          maxItems: 128
          type: array
          items:
            type: string
          nullable: true
        datePosted:
          description: The date of the posting
          type: string
          allOf:
            - $ref: '#/components/schemas/LocalDate'
          nullable: true
        applicationDeadline:
          description: The deadline for the application
          type: string
          allOf:
            - $ref: '#/components/schemas/LocalDate'
          nullable: true
    JobApplication:
      description: Job Application
      required:
        - jobApplicationId
        - jobPostingId
        - jaData
      type: object
      properties:
        jobApplicationId:
          description: Internal Job Application id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        jobPostingId:
          description: Internal Job Posting id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        jaData:
          description: Job Application data
          type: object
          allOf:
            - $ref: '#/components/schemas/JAData'
    JobListResult:
      required:
        - list
      type: object
      properties:
        list:
          type: array
          items:
            type: string
        total:
          format: int32
          type: integer
    JobPosting:
      description: Job Posting
      required:
        - jobPostingId
        - jpData
      type: object
      properties:
        jobPostingId:
          description: internal Job Posting id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        jpData:
          description: Job Posting data
          type: object
          allOf:
            - $ref: '#/components/schemas/JPData'
    JsonNode:
      type: object
      properties:
        empty:
          type: boolean
        valueNode:
          type: boolean
        containerNode:
          type: boolean
        missingNode:
          type: boolean
        array:
          type: boolean
        object:
          type: boolean
        nodeType:
          $ref: '#/components/schemas/JsonNodeType'
        pojo:
          type: boolean
        number:
          type: boolean
        integralNumber:
          type: boolean
        floatingPointNumber:
          type: boolean
        short:
          type: boolean
        int:
          type: boolean
        long:
          type: boolean
        float:
          type: boolean
        double:
          type: boolean
        bigDecimal:
          type: boolean
        bigInteger:
          type: boolean
        textual:
          type: boolean
        boolean:
          type: boolean
        'null':
          type: boolean
        binary:
          type: boolean
    JsonNodeType:
      enum:
        - ARRAY
        - BINARY
        - BOOLEAN
        - MISSING
        - 'NULL'
        - NUMBER
        - OBJECT
        - POJO
        - STRING
      type: string
    JsonObject:
      type: array
      items:
        type: object
        properties:
          key:
            type: string
          value: {}
    Kind:
      enum:
        - CHANNEL
        - USER
        - ALL
      type: string
    Language:
      enum:
        - BG
        - CS
        - DA
        - DE
        - EL
        - EN
        - ES
        - ET
        - FI
        - FR
        - HU
        - ID
        - IT
        - JA
        - KO
        - LT
        - LV
        - NB
        - NL
        - PL
        - PT
        - RO
        - RU
        - SK
        - SL
        - SV
        - TR
        - UK
        - ZH
      type: string
    ListUploadJobsResult:
      description: List of the upload jobs
      required:
        - list
      type: object
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/ProcessJob'
        total:
          format: int32
          description: Total number of jobs in the queue.
          type: integer
        totalJobs:
          format: int32
          description: Total number of jobs in the queue with specified filter.
          type: integer
    ListUploadsResult:
      description: List uploads result
      required:
        - list
      type: object
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/Upload'
        total:
          format: int64
          type: integer
    LocalDate:
      format: date
      type: string
      example: '2022-03-10'
    LocalDateTime:
      format: date-time
      type: string
      example: '2022-03-10T12:15:50'
    Location:
      description: User's location preferences
      type: object
      properties:
        geo:
          allOf:
            - $ref: '#/components/schemas/Geo'
          nullable: true
        name:
          type: string
          nullable: true
        autoUpdate:
          type: boolean
        show:
          type: boolean
    LoginType:
      enum:
        - EMAIL
        - USERNAME
        - PHONE
        - PASSKEY
        - IMPERSONATE
      type: string
    Manifest:
      required:
        - id
        - name
        - description
        - version
        - releasedOn
        - developer
        - icons
        - previews
        - routes
        - visibility
        - type
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        version:
          type: string
        releasedOn:
          $ref: '#/components/schemas/Instant'
        developer:
          $ref: '#/components/schemas/ApplicationDeveloper'
        icons:
          type: array
          items:
            type: string
        previews:
          type: array
          items:
            type: string
        routes:
          type: array
          items:
            $ref: '#/components/schemas/Route'
        visibility:
          $ref: '#/components/schemas/ApplicationVisibility'
        type:
          $ref: '#/components/schemas/ApplicationType'
        standard:
          type: boolean
    Meta:
      type: object
      properties:
        blurhash:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        altText:
          type: string
          nullable: true
    Meta1:
      type: object
      properties:
        duration:
          format: double
          description: Video duration in seconds
          type: number
          nullable: true
        width:
          format: int32
          description: Media width
          type: integer
          nullable: true
        height:
          format: int32
          description: Media height
          type: integer
          nullable: true
        codec:
          description: Video codec
          type: string
          nullable: true
        rotate:
          format: int32
          description: Rotation in degrees
          type: integer
          nullable: true
    MetricsData:
      description: Metrics data for a specific time period
      required:
        - granularity
        - timeSlot
      type: object
      properties:
        granularity:
          description: Time granularity of the metrics
          type: string
          allOf:
            - $ref: '#/components/schemas/TimeGranularity'
        timeSlot:
          description: Time slot for which metrics are calculated
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
        newSignups:
          format: int64
          description: Number of new signups
          type: integer
          nullable: true
        activeUsers:
          format: int64
          description: Number of active users
          type: integer
          nullable: true
        userCreations:
          format: int64
          description: Number of users created
          type: integer
          nullable: true
        userDeletions:
          format: int64
          description: Number of users deleted
          type: integer
          nullable: true
        usersWhoPosted:
          format: int64
          description: Number of unique users who posted
          type: integer
          nullable: true
        mediaPosts:
          format: int64
          description: Number of posts with media attachments
          type: integer
          nullable: true
        likes:
          format: int64
          description: Number of likes
          type: integer
          nullable: true
        reposts:
          format: int64
          description: Number of reposts
          type: integer
          nullable: true
        quotes:
          format: int64
          description: Number of quote posts
          type: integer
          nullable: true
        replies:
          format: int64
          description: Number of replies
          type: integer
          nullable: true
        conversations:
          format: int64
          description: Number of conversations
          type: integer
          nullable: true
        users:
          format: int64
          description: Total number of local users on this day
          type: integer
          nullable: true
        groups:
          format: int64
          description: Total number of local groups (not deleted) on this day
          type: integer
          nullable: true
        localPostsCreated:
          format: int64
          description: Local top-level posts created this day
          type: integer
          nullable: true
        localPostsTotal:
          format: int64
          description: Cumulative local top-level posts up to this day
          type: integer
          nullable: true
        remotePostsCreated:
          format: int64
          description: Remote top-level posts created this day
          type: integer
          nullable: true
        remotePostsTotal:
          format: int64
          description: Cumulative remote top-level posts up to this day
          type: integer
          nullable: true
        localComments:
          format: int64
          description: Comments by local users created this day
          type: integer
          nullable: true
        remoteComments:
          format: int64
          description: Comments by remote users created this day
          type: integer
          nullable: true
        localCommentsTotal:
          format: int64
          description: Cumulative comments by local users up to this day
          type: integer
          nullable: true
        remoteCommentsTotal:
          format: int64
          description: Cumulative comments by remote users up to this day
          type: integer
          nullable: true
        domains:
          format: int64
          description: Total number of external domains on this day
          type: integer
          nullable: true
    MetricsPeriod:
      description: Predefined time periods for metrics queries
      enum:
        - LAST_DAY
        - LAST_WEEK
        - LAST_MONTH
      type: string
    MetricsSummary:
      required:
        - operationMetrics
        - totals
      type: object
      properties:
        operationMetrics:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/GlobalAggregatedMetrics'
        totals:
          $ref: '#/components/schemas/MetricsSummaryTotals'
    MetricsSummaryTotals:
      type: object
      properties:
        totalMeasurements:
          format: int64
          type: integer
        totalTime:
          format: int64
          type: integer
        overallAverage:
          format: double
          type: number
        operationCount:
          format: int32
          type: integer
        ownerTypeCount:
          format: int32
          type: integer
    MuteState:
      type: object
      properties:
        state:
          type: boolean
        expiresAt:
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
    Name:
      required:
        - common
        - official
        - nativeName
      type: object
      properties:
        common:
          type: string
        official:
          type: string
        nativeName:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/NativeName'
    Namespace:
      enum:
        - Platform
        - User
        - Group
        - GroupMember
      type: string
    NativeName:
      required:
        - official
        - common
      type: object
      properties:
        official:
          type: string
        common:
          type: string
    NoteUpdate:
      required:
        - userId
        - text
      type: object
      properties:
        userId:
          description: User id to set note for
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        text:
          description: Note text
          maxLength: 500
          minLength: 1
          pattern: \S
          type: string
    Notification:
      required:
        - id
        - userId
        - type
        - status
        - meta
        - createdAt
      type: object
      properties:
        id:
          description: Internal notification id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: nt_01hz1f0sj42k87a6s2nzpc4s92n
        userId:
          description: User receiving the notification
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: us_01hz1fkfg82hf89s2nzqwer02r
        type:
          $ref: '#/components/schemas/NotificationType'
        status:
          $ref: '#/components/schemas/NotificationStatus'
        activityId:
          description: Related activity id (usually a post)
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: pt_01hz1f0jkdw3h27a2kdr8sn2kt
          nullable: true
        fromUserId:
          description: User who triggered the notification
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: us_01hz1frg9sf48d7a8sn2kdr8w3h
          nullable: true
        meta:
          $ref: '#/components/schemas/NotificationMeta'
        createdAt:
          $ref: '#/components/schemas/Instant'
        updatedAt:
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        fromUser:
          allOf:
            - $ref: '#/components/schemas/User'
          nullable: true
        post:
          allOf:
            - $ref: '#/components/schemas/Post'
          nullable: true
    NotificationAction:
      required:
        - action
        - text
      type: object
      properties:
        action:
          type: string
        text:
          type: string
    NotificationDelivery:
      description: |2-

            IMMEDIATELY
                Notification is delivered immediately.
            BUFFERED
                Notification delivery is delayed, notifications are buffered and might not
                be delivered if expired during buffering.
            
      enum:
        - IMMEDIATELY
        - BUFFERED
      type: string
    NotificationMeta:
      type: object
      properties:
        actionsAvailable:
          type: array
          items:
            $ref: '#/components/schemas/NotificationAction'
          nullable: true
        actionsTaken:
          type: array
          items:
            $ref: '#/components/schemas/NotificationAction'
          nullable: true
        empty:
          type: boolean
    NotificationStatus:
      enum:
        - UNREAD
        - READ
        - BLOCKED
        - HIDDEN
      type: string
    NotificationStrategy:
      description: |2-

            FIRST
                First notification is delivered only. All consecutive notifications are ignored.
            LAST
                New notification is delivered. Previous notifications are removed.
            MANY
                New notification is delivered. Old notifications are kept intact.
            
      enum:
        - FIRST
        - LAST
        - MANY
      type: string
    NotificationType:
      description: |2-

            FOLLOW
                New follower

                Send to the user who got a new follower.

            FOLLOW_REQUEST
                New follower request

                Similar to FOLLOW, send to the user who got a new follower,
                but in cases where followers need to be explicitly approved.

            GROUP_INVITE
                User got an invitation

                Send to the user who received the ActivityPub invitation activity.

            LIKE
                Post has been liked

                Send to the post's author as soon as another user likes their post.

            COMMENT
                Post has been commented on

                Send to the post's author and all users subscribed to the post.

            MENTION
                User has been mentioned in a post or comment

                Send to the user who was mentioned in the post or comment.

            REPOST
                Post has been reposted

                Send to the author of the post that was reposted.

            LIST_POST_CREATE
                New post or comment in list

                Send to the list owner when a new post is created by a list user.

            POST_UPDATE
                Post or comment has been updated

                Send to users subscribed to the post or comment.

            POLL
                Poll has been closed (expired)

                Send to the poll's author and all voters.

            EVENT_INVITE
                User has been invited to a private event

                Send to the invitee, i.e., the user invited to the event.

            EVENT_REVOKE
                User's invitation has been revoked

                Send to the invitee, i.e., the user whose invitation was revoked.

            EVENT_JOIN
                User joined a public event

                Send to the event organizer.

            EVENT_CANCEL
                Event has been cancelled

                Send to all event attendees (for public events, to users who joined).

            EVENT_UPDATE
                Event has been updated

                Send to all event attendees (for public events, to users who joined).
            
      enum:
        - FOLLOW
        - FOLLOW_REQUEST
        - GROUP_INVITE
        - LIKE
        - COMMENT
        - MENTION
        - REPOST
        - LIST_POST_CREATE
        - POST_UPDATE
        - POLL
        - EVENT_INVITE
        - EVENT_JOIN
        - EVENT_CANCEL
        - EVENT_UPDATE
      type: string
    Option:
      required:
        - title
      type: object
      properties:
        title:
          type: string
    OverallStats:
      required:
        - finished
        - failed
      type: object
      properties:
        finished:
          type: object
          additionalProperties:
            format: int64
            type: integer
        failed:
          type: object
          additionalProperties:
            format: int64
            type: integer
    Passkey:
      required:
        - credentialId
        - accountId
        - userId
        - publicKeyCose
      type: object
      properties:
        credentialId:
          type: string
        accountId:
          $ref: '#/components/schemas/TypeId'
        userId:
          $ref: '#/components/schemas/TypeId'
        publicKeyCose:
          format: binary
          type: string
        publicKeyAlg:
          format: int64
          type: integer
        aaguid:
          type: string
          nullable: true
        signCount:
          format: int64
          type: integer
    PasswordChangeRequest:
      description: Params to change account password
      required:
        - currentPassword
        - newPassword
      type: object
      properties:
        currentPassword:
          description: Current account password
          maxLength: 64
          minLength: 1
          type: string
          example: PassW0rd!
        newPassword:
          description: New password, enforced by password policy
          type: string
          example: PassW0rd!
    PasswordPolicy:
      enum:
        - ANY
        - STRICT
      type: string
    PasswordRecoveryChange:
      description: Params to change account password after recovery
      required:
        - login
        - newPassword
      type: object
      properties:
        login:
          description: Email or username
          type: string
          example: user@gmail.com or john_smith
        newPassword:
          description: New password, enforced by password policy
          type: string
          example: PassW0rd!
    PasswordRecoveryCode:
      description: Params to confirm request to change password with recovery code
      required:
        - login
        - code
      type: object
      properties:
        login:
          description: Email or username
          type: string
          example: user@gmail.com or john_smith
        code:
          format: int32
          description: Confirmation code
          type: integer
          example: 854882
    PasswordRecoveryRequest:
      description: Params to recover account password
      required:
        - login
      type: object
      properties:
        login:
          description: Email or username
          type: string
          example: user@gmail.com or john_smith
    PhoneSignup:
      required:
        - phone
        - username
        - displayName
      type: object
      properties:
        phone:
          description: Phone number
          type: string
          example: '+12345678901'
        username:
          description: Username of the main user
          type: string
          example: john_smith
        displayName:
          description: Display Name of the main user
          maxLength: 56
          minLength: 1
          type: string
          example: John Smith
        inviteCode:
          description: Optional invite code
          type: string
          example: abcd-efgh-1234
          nullable: true
    PinnedParam:
      description: |2-

                    Options for '?pinned' param when loading requests list of posts. Applied only if ?userId is present.
                    * ONLY - load only pinned posts
                    * SKIP - skip pinned posts
                    * ALL  - both, has the same effect as omitting the param
                    
      enum:
        - ONLY
        - SKIP
        - ALL
      type: string
    Poll:
      required:
        - id
        - options
      type: object
      properties:
        id:
          description: Internal poll id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: pl_01hz1f0jnm2f87w2mzpc4s92kt
        expiresAt:
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        multiple:
          type: boolean
        votersCount:
          format: int64
          type: integer
        options:
          type: array
          items:
            $ref: '#/components/schemas/PollOption'
        hideTotals:
          type: boolean
        ownVotes:
          type: array
          items:
            format: int32
            type: integer
          nullable: true
        emojis:
          type: array
          items:
            $ref: '#/components/schemas/Emoji'
          nullable: true
    Poll1:
      required:
        - id
        - options
      type: object
      properties:
        id:
          type: string
        options:
          type: array
          items:
            $ref: '#/components/schemas/Option'
    PollCreate:
      description: Poll creation params
      required:
        - options
        - expiresIn
        - multiple
        - hideTotals
      type: object
      properties:
        options:
          description: List of poll options
          maxItems: 5
          minItems: 2
          type: array
          items:
            type: string
        expiresIn:
          format: double
          description: Duration in seconds
          type: number
          allOf:
            - $ref: '#/components/schemas/Duration'
        multiple:
          description: Allow multiple choices
          type: boolean
        hideTotals:
          description: Hide totals until poll finishes
          type: boolean
    PollOption:
      required:
        - title
      type: object
      properties:
        title:
          type: string
        votesCount:
          format: int64
          type: integer
    Post:
      description: User's post
      required:
        - id
        - uri
        - text
        - path
        - privacy
        - kind
        - software
        - ownerId
        - ownerType
        - summary
        - tags
        - mentions
        - stats
        - settings
        - mediaType
        - createdAt
        - updatedAt
        - author
        - uploads
        - conversationId
      type: object
      properties:
        id:
          description: internal post id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        uri:
          format: uri
          description: unique post uri
          type: string
        text:
          description: post text, raw or html depending on how it was requested
          type: string
        path:
          description: replies path
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
        privacy:
          description: post privacy level
          type: string
          allOf:
            - $ref: '#/components/schemas/PostPrivacy'
          example: PUBLIC
        kind:
          description: Article or Note
          type: string
          allOf:
            - $ref: '#/components/schemas/PostKind'
          example: Note
        software:
          description: post software
          type: string
          example: wellesley
        repostOf:
          description: id of a post this one was reposted from
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        ownerId:
          $ref: '#/components/schemas/TypeId'
        ownerType:
          $ref: '#/components/schemas/PostOwnerType'
        groupId:
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        title:
          type: string
          nullable: true
        summary:
          description: >-
            Subject or summary line, below which post content is collapsed until
            expanded.
          type: string
          nullable: true
        tags:
          description: List of tags
          type: array
          items:
            type: string
        mentions:
          description: List of mentions
          type: array
          items:
            format: uri
            type: string
        stats:
          description: Stats
          type: object
          allOf:
            - $ref: '#/components/schemas/PostStats'
        settings:
          description: Settings
          type: object
          allOf:
            - $ref: '#/components/schemas/PostSettings'
        lang:
          allOf:
            - $ref: '#/components/schemas/Language'
          nullable: true
        poll:
          allOf:
            - $ref: '#/components/schemas/Poll'
          nullable: true
        card:
          description: Preview card for any links in the post
          type: object
          allOf:
            - $ref: '#/components/schemas/Card'
          nullable: true
        mediaType:
          description: >-
            Post media type. Default for Note is text/plain, for Article
            text/markdown
          type: string
          allOf:
            - $ref: '#/components/schemas/PostMediaType'
        translations:
          type: object
          additionalProperties:
            type: string
          nullable: true
        createdAt:
          $ref: '#/components/schemas/Instant'
        updatedAt:
          $ref: '#/components/schemas/Instant'
        author:
          $ref: '#/components/schemas/User'
        uploads:
          type: array
          items:
            $ref: '#/components/schemas/Upload'
        liked:
          description: Whether the current user liked it or not
          type: boolean
          nullable: true
        reposted:
          description: Whether the current user reposted it or not
          type: boolean
          nullable: true
        quoted:
          description: Whether the current user quoted it or not
          type: boolean
          nullable: true
        muted:
          description: Whether the current user muted the author of the post
          type: boolean
          nullable: true
        blocked:
          description: Whether the current user blocked the author of the post
          type: boolean
          nullable: true
        visible:
          description: Whether the current user can see it or not (e.g. FOLLOWERS_ONLY
          type: boolean
          nullable: true
        pinned:
          description: Whether the current user pinned it or not
          type: boolean
          nullable: true
        bookmarked:
          description: Whether the current user bookmarked it or not
          type: boolean
          nullable: true
        edited:
          description: Whether the post was edited
          type: boolean
          nullable: true
        deleted:
          type: boolean
          nullable: true
        emojis:
          type: array
          items:
            $ref: '#/components/schemas/Emoji'
          nullable: true
        replies:
          type: array
          items:
            $ref: '#/components/schemas/Post'
          nullable: true
        repostedBy:
          description: List of users who reposted this post
          type: array
          items:
            $ref: '#/components/schemas/UserLite'
          nullable: true
        originalPost:
          description: >-
            Original of repost/quote. In WS context or /replies API could also
            be parent of a comment
          type: object
          allOf:
            - $ref: '#/components/schemas/Post'
          nullable: true
        votes:
          description: Votes summary
          type: object
          allOf:
            - $ref: '#/components/schemas/PostVotesSummary'
          nullable: true
        remote:
          type: boolean
        repostAny:
          type: boolean
        repost:
          type: boolean
        quote:
          type: boolean
        own:
          type: boolean
        replyTo:
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        conversationId:
          $ref: '#/components/schemas/TypeId'
    PostActivity:
      required:
        - user
        - createdAt
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
        createdAt:
          $ref: '#/components/schemas/Instant'
    PostAttachment:
      required:
        - postId
        - uploadId
      type: object
      properties:
        postId:
          $ref: '#/components/schemas/TypeId'
        uploadId:
          $ref: '#/components/schemas/TypeId'
    PostDelete:
      required:
        - reason
      type: object
      properties:
        postId:
          description: ID of a specific post to delete. Mutually exclusive with reportId.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: ps_01hxcvk1hjexere4pvtrj0ymqq
          nullable: true
        reportId:
          description: >-
            ID of a report whose associated posts should be deleted. Mutually
            exclusive with postId.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: rp_01hxcvk1hjexere4pvtrj0ymqq
          nullable: true
        reason:
          description: >-
            Reason for deleting the post(s). Will be recorded in audit logs and
            report notes.
          type: string
          example: Violates community guidelines - hate speech
    PostEdit:
      required:
        - id
        - text
        - uploads
        - mentions
        - pollOptions
        - createdAt
        - ownerType
      type: object
      properties:
        id:
          $ref: '#/components/schemas/TypeId'
        text:
          type: string
        summary:
          type: string
          nullable: true
        sensitive:
          type: boolean
          nullable: true
        uploads:
          type: array
          items:
            $ref: '#/components/schemas/Upload'
        mentions:
          type: array
          items:
            format: uri
            type: string
        pollOptions:
          type: array
          items:
            type: string
        createdAt:
          $ref: '#/components/schemas/Instant'
        card:
          allOf:
            - $ref: '#/components/schemas/Card'
          nullable: true
        emojis:
          type: array
          items:
            $ref: '#/components/schemas/Emoji'
          nullable: true
        ownerType:
          $ref: '#/components/schemas/PostOwnerType'
    PostKind:
      enum:
        - Note
        - Article
      type: string
    PostMediaType:
      enum:
        - TEXT_PLAIN
        - MARKDOWN
      type: string
    PostOwnerType:
      description: |2-

            Owner types for posts:
              * USER - user’s channel (personal or group channel)
              * EVENT - event (personal or group)
              * CATEGORY - forum category

              ** POST OWNER: **
              - Personal channel
                  - userId = author
                  - ownerId = userId (Type.USER)
                  - ownerType = USER
                  - groupId = null
              - Forum post
                  - userId = author
                  - ownerId = categoryId (Type.CATEGORY)
                  - ownerType = CATEGORY
                  - groupId = forum’s groupId
              - Personal event
                  - userId = author
                  - ownerId = eventId (Type.EVENT)
                  - ownerType = EVENT
                  - groupId = null
              - Group channel
                  - userId = author
                  - ownerId = channel userId (Type.USER)
                  - ownerType = USER
                  - groupId = groupId
              - Group event
                  - userId = author
                  - ownerId = eventId (Type.EVENT)
                  - ownerType = EVENT
                  - groupId = groupId
               
      enum:
        - USER
        - EVENT
        - CATEGORY
      type: string
    PostPrivacy:
      description: |2-

            Privacy levels for posts:
              * PUBLIC - post is visible to anyone, including people who are not logged in and those who do not follow the user.
                         It appears in the public timelines (home, local, and federated).
              * UNLISTED - post is visible to anyone who visits the user's profile, but it does not appear in public timelines.
                         Only followers and those who visit the user's profile directly can see it.
              * PRIVATE - post is only visible to the user's followers. It does not appear in public timelines or on the user's profile for non-followers.
              * DIRECT - post is visible only to the mentioned users. It functions like a direct message and is not visible on public timelines, the user's profile, or to followers.
              * FOLLOW_POST - comment only. Follow parent post visibility
               
      enum:
        - PUBLIC
        - UNLISTED
        - PRIVATE
        - DIRECT
        - FOLLOW_POST
      type: string
    PostSettings:
      type: object
      properties:
        commentsEnabled:
          type: boolean
        sensitive:
          type: boolean
    PostStats:
      required:
        - reactions
        - lastActivity
        - lastViewTimestamp
      type: object
      properties:
        likes:
          format: int32
          type: integer
        reposts:
          format: int32
          type: integer
        quotes:
          format: int32
          type: integer
        comments:
          format: int32
          type: integer
        views:
          format: int32
          type: integer
        bookmarks:
          format: int32
          type: integer
        reactions:
          type: object
          additionalProperties:
            format: int32
            type: integer
        watchTime:
          format: int64
          type: integer
          nullable: true
        secondsToFirstAnswer:
          format: int32
          type: integer
          nullable: true
        secondsToAccepted:
          format: int32
          type: integer
          nullable: true
        lastActivity:
          $ref: '#/components/schemas/Instant'
        lastViewTimestamp:
          $ref: '#/components/schemas/Instant'
    PostTranslation:
      required:
        - text
        - media_attachments
      type: object
      properties:
        text:
          type: string
        spoiler_text:
          type: string
          nullable: true
        media_attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        poll:
          allOf:
            - $ref: '#/components/schemas/Poll1'
          nullable: true
        detected_source_language:
          type: string
          nullable: true
        provider:
          type: string
          nullable: true
    PostVotesSummary:
      required:
        - upvotes
        - downvotes
      type: object
      properties:
        upvotes:
          format: int32
          description: upvotes count
          type: integer
        downvotes:
          format: int32
          description: downvotes count
          type: integer
        ownVote:
          format: int32
          description: current user's vote, if any
          type: integer
          nullable: true
    ProcessJob:
      required:
        - jobId
        - uploadId
        - uploadType
        - properties
        - createdAt
        - updatedAt
      type: object
      properties:
        jobId:
          $ref: '#/components/schemas/TypeId'
        uploadId:
          $ref: '#/components/schemas/TypeId'
        uploadType:
          $ref: '#/components/schemas/UploadType'
        originalFileSize:
          format: int64
          type: integer
        attempts:
          format: int32
          type: integer
        progress:
          format: double
          type: number
        properties:
          type: array
          items:
            $ref: '#/components/schemas/ActionProperties'
        deleteOriginal:
          type: boolean
        error:
          type: string
          nullable: true
        startedAt:
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        finishedAt:
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        createdAt:
          $ref: '#/components/schemas/Instant'
        updatedAt:
          $ref: '#/components/schemas/Instant'
        upload:
          allOf:
            - $ref: '#/components/schemas/Upload'
          nullable: true
    PubKeyCredParam:
      type: object
      properties:
        type:
          type: string
          nullable: true
        alg:
          format: int64
          type: integer
          nullable: true
    PublicKeyCredentialCreationOptions:
      required:
        - challenge
      type: object
      properties:
        challenge:
          description: Base64url-encoded server challenge
          type: string
        rp:
          description: Relying Party entity (name and id)
          type: object
          allOf:
            - $ref: '#/components/schemas/RpEntity'
          nullable: true
        user:
          description: User entity; id is base64url-encoded
          type: object
          allOf:
            - $ref: '#/components/schemas/UserEntity'
          nullable: true
        pubKeyCredParams:
          description: List of acceptable credential parameters (type and COSE alg)
          type: array
          items:
            $ref: '#/components/schemas/PubKeyCredParam'
          nullable: true
        timeout:
          format: int64
          description: Timeout in milliseconds
          type: integer
          nullable: true
        attestation:
          description: Attestation conveyance preference
          type: string
          nullable: true
        authenticatorSelection:
          description: Authenticator selection constraints
          type: object
          allOf:
            - $ref: '#/components/schemas/AuthenticatorSelectionCriteria'
          nullable: true
        excludeCredentials:
          description: Credentials to exclude from creation (by descriptor)
          type: array
          items:
            $ref: '#/components/schemas/PublicKeyCredentialDescriptor'
          nullable: true
        extensions:
          description: Extension inputs keyed by extension name
          type: object
          additionalProperties: {}
          nullable: true
    PublicKeyCredentialDescriptor:
      type: object
      properties:
        type:
          type: string
          nullable: true
        id:
          type: string
          nullable: true
        transports:
          type: array
          items:
            type: string
          nullable: true
    PublicKeyCredentialRequestOptions:
      description: Options for passkey authentication
      required:
        - challenge
        - timeout
        - rpId
      type: object
      properties:
        challenge:
          description: Base64url-encoded challenge
          type: string
        timeout:
          format: int64
          description: Timeout in milliseconds
          type: integer
        rpId:
          description: Relying Party ID
          type: string
        allowCredentials:
          description: List of allowed credentials for assertion (by descriptor)
          type: array
          items:
            $ref: '#/components/schemas/PublicKeyCredentialDescriptor'
          nullable: true
        userVerification:
          description: User verification requirement (preferred/required/discouraged)
          type: string
          nullable: true
        extensions:
          description: Extension inputs keyed by extension name
          type: object
          additionalProperties: {}
          nullable: true
    PublicPoint:
      type: object
      properties:
        data:
          type: array
          items:
            format: int32
            type: integer
    Publisher:
      type: object
      properties:
        name:
          type: string
          nullable: true
        url:
          type: string
          nullable: true
        logo:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
    Question:
      description: >-
        A question that prospective group members must answer during the join
        process. Questions are used to screen members when a group's join mode
        is set to QUESTIONS.
      required:
        - questionText
        - type
        - choices
        - ordering
        - id
      type: object
      properties:
        questionText:
          description: The question text displayed to users (max 200 characters)
          maxLength: 200
          pattern: \S
          type: string
          example: Why do you want to join this group?
        type:
          description: >-
            Question type determining the answer format (TEXT, SINGLE_CHOICE,
            MULTIPLE_CHOICE)
          type: string
          allOf:
            - $ref: '#/components/schemas/QuestionType'
        choices:
          description: >-
            Available choices for SINGLE_CHOICE or MULTIPLE_CHOICE questions.
            Empty for TEXT questions.
          type: array
          items:
            $ref: '#/components/schemas/Choice'
        ordering:
          format: int32
          description: Display order position - questions with lower values appear first
          minimum: 0
          type: integer
          example: 1000
        id:
          description: Unique identifier for the question
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: qu_01hz1f0gs9fe4a37jzvzn9m96k
    QuestionAnswer:
      description: Stored question answers for a user and group
      required:
        - answerId
        - groupId
        - userId
        - answers
        - answerToken
        - createdAt
      type: object
      properties:
        answerId:
          description: Unique answer ID
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        groupId:
          description: Group ID the answers are for
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        userId:
          description: User ID who submitted the answers
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        answers:
          description: The submitted answers
          type: array
          items:
            $ref: '#/components/schemas/Answer'
        answerToken:
          description: Token for group joining
          type: string
        createdAt:
          description: When the answers were submitted
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
    QuestionAnswerCreate:
      description: >-
        Request payload for submitting answers to all required group entry
        questions. Must include an answer for each active question in the group.
      required:
        - answers
      type: object
      properties:
        answers:
          description: Complete list of answers corresponding to all group questions
          type: array
          items:
            $ref: '#/components/schemas/Answer'
    QuestionAnswerResponse:
      description: >-
        Response returned after successfully submitting answers to group
        questions. Contains a token that must be provided when calling the group
        join endpoint.
      required:
        - answerToken
        - submittedAt
      type: object
      properties:
        answerToken:
          description: >-
            Authentication token to be used with the group join endpoint. Has a
            limited validity period.
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        submittedAt:
          description: ISO 8601 timestamp indicating when the answers were submitted
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2024-01-15T10:30:00Z'
    QuestionCreate:
      description: >-
        Request payload for creating a new group question. Provide choices only
        for SINGLE_CHOICE and MULTIPLE_CHOICE question types.
      required:
        - questionText
        - type
        - choices
        - ordering
      type: object
      properties:
        questionText:
          description: The question text displayed to users (max 200 characters)
          maxLength: 200
          pattern: \S
          type: string
          example: Why do you want to join this group?
        type:
          description: >-
            Question type determining the answer format (TEXT, SINGLE_CHOICE,
            MULTIPLE_CHOICE)
          type: string
          allOf:
            - $ref: '#/components/schemas/QuestionType'
        choices:
          description: >-
            Available choices for SINGLE_CHOICE or MULTIPLE_CHOICE questions.
            Empty for TEXT questions.
          type: array
          items:
            $ref: '#/components/schemas/Choice'
        ordering:
          format: int32
          description: Display order position - questions with lower values appear first
          minimum: 0
          type: integer
          example: 1000
    QuestionType:
      description: >-
        The type of question that determines the expected answer format and
        validation rules
      enum:
        - TEXT
        - MULTIPLE_CHOICE
        - SINGLE_CHOICE
      type: string
    QuestionUpdate:
      description: >-
        Request payload for updating an existing question. All fields are
        required and will replace the current values. Ensure choices array
        matches the question type.
      required:
        - questionText
        - type
        - choices
        - ordering
      type: object
      properties:
        questionText:
          description: The question text displayed to users (max 200 characters)
          maxLength: 200
          pattern: \S
          type: string
          example: Why do you want to join this group?
        type:
          description: >-
            Question type determining the answer format (TEXT, SINGLE_CHOICE,
            MULTIPLE_CHOICE)
          type: string
          allOf:
            - $ref: '#/components/schemas/QuestionType'
        choices:
          description: >-
            Available choices for SINGLE_CHOICE or MULTIPLE_CHOICE questions.
            Empty for TEXT questions.
          type: array
          items:
            $ref: '#/components/schemas/Choice'
        ordering:
          format: int32
          description: Display order position - questions with lower values appear first
          minimum: 0
          type: integer
          example: 1000
    QueueSummary:
      required:
        - queue
      type: object
      properties:
        queue:
          $ref: '#/components/schemas/UploadJobsQueue'
        count:
          format: int32
          type: integer
        averageTimeInQueueMillis:
          format: int64
          type: integer
        oldestTimeInQueueMillis:
          format: int64
          type: integer
        averageProcessingTimeMillis:
          format: int64
          type: integer
        averageWaitingTimeMillis:
          format: int64
          type: integer
        p95TimeInQueueMillis:
          format: int64
          type: integer
        successCount:
          format: int32
          type: integer
        failureCount:
          format: int32
          type: integer
    RBACPermissions:
      description: Type-safe collection of resource-specific access permissions
      required:
        - resourceAccess
      type: object
      properties:
        resourceAccess:
          description: List of type-safe resource-specific access controls
          type: array
          items:
            $ref: '#/components/schemas/RBACResourceAccess'
    RBACResourceAccess:
      description: Defines type-safe access permissions for a specific resource
      required:
        - resource
        - actions
      type: object
      properties:
        resource:
          description: The type-safe resource being controlled
          type: string
        actions:
          description: List of allowed type-safe actions for this resource
          type: array
          items:
            type: string
    RBACRole:
      description: Represents a role within the RBAC (Role-Based Access Control) system
      required:
        - roleId
        - name
        - permissions
        - createdAt
        - updatedAt
      type: object
      properties:
        roleId:
          description: Unique identifier for the role
          type: string
          allOf:
            - $ref: '#/components/schemas/RoleId'
          example: rr_01hxcvk1hjexere4pvtrj0ymqq
        name:
          description: Name of the role, unique within its scope
          type: string
          example: ADMIN
        description:
          description: Optional description of the role's purpose and responsibilities
          type: string
          example: System administrator with full access
          nullable: true
        permissions:
          description: Set of permissions assigned to this role
          type: object
          allOf:
            - $ref: '#/components/schemas/RBACPermissions'
        createdAt:
          description: Timestamp when the role was created
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2023-01-01T00:00:00Z'
        updatedAt:
          description: Timestamp when the role was last updated
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2023-01-01T00:00:00Z'
    RBACRoleTemplate:
      description: Template for creating new RBAC roles
      required:
        - name
        - scope
        - permissions
      type: object
      properties:
        name:
          description: Name of the role, unique within its scope
          type: string
          example: user
        description:
          description: Optional description of the role's purpose and responsibilities
          type: string
          example: The regular user
          nullable: true
        scope:
          description: |2-

                        The scope in which the role is valid.
                        The scope can be Global (hardcoded), currently the only one is "System".
                        Also the scope can be dynamic, currently we use Group Id, like "gr_05hxcvk1hjexere4pvtrj0hggt"
                    
          type: string
          example: System
        permissions:
          description: Set of permissions to be assigned to this role
          type: object
          allOf:
            - $ref: '#/components/schemas/RBACPermissions'
    RedisJob:
      required:
        - jobHash
        - job
        - queueName
      type: object
      properties:
        jobHash:
          $ref: '#/components/schemas/UUID'
        job:
          type: string
        queueName:
          type: string
        tries:
          format: int32
          type: integer
        startTime:
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        lastTryAt:
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        lastError:
          type: string
          nullable: true
        endTime:
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
    RedisJobsResult:
      required:
        - list
      type: object
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/RedisJob'
        total:
          format: int32
          type: integer
    RegistrationMode:
      description: |2-

            Registration mode:
              * OPEN - everybody can sign up.
              * APPROVAL - approval is required for sign up.
              * EMAIL_DOMAIN_ALLOWLIST - only users with emails from the configured allowlist can sign up.
              * CLOSED - new sign ups are closed.
               
      enum:
        - OPEN
        - APPROVAL
        - EMAIL_DOMAIN_ALLOWLIST
        - CLOSED
      type: string
    RegistrationRequest:
      required:
        - name
        - baseUrl
        - serverId
        - publicKey
      type: object
      properties:
        name:
          type: string
        baseUrl:
          format: uri
          type: string
        serverId:
          type: string
        publicKey:
          $ref: '#/components/schemas/Ed25519PublicKey'
    RegistrationResponse:
      required:
        - hash
        - nextStep
      type: object
      properties:
        hash:
          type: string
        nextStep:
          $ref: '#/components/schemas/SignupRequestStep'
    Relationship:
      description: Relationship between the viewer and a target user
      type: object
      properties:
        following:
          description: Does the viewer follow the target?
          enum:
            - PENDING
            - ACCEPTED
            - REJECTED
          type: string
          nullable: true
        followed:
          description: Does the target follow the viewer?
          enum:
            - PENDING
            - ACCEPTED
            - REJECTED
          type: string
          nullable: true
        blocked:
          description: Viewer blocked the target
          type: boolean
          nullable: true
        blockedBy:
          description: Target blocked the viewer
          type: boolean
          nullable: true
        muted:
          description: Viewer mutes the target
          type: object
          allOf:
            - $ref: '#/components/schemas/MuteState'
          nullable: true
        note:
          description: Viewer's private note about the target
          type: string
          nullable: true
    RemoteFileInfo:
      description: >-
        Contains uri and file extension of the remote file. The uri should be a
        valid URL.
      required:
        - uri
        - extension
      type: object
      properties:
        uri:
          format: uri
          type: string
        extension:
          type: string
    Report:
      required:
        - id
        - uri
        - comment
        - createdAt
        - updatedAt
        - notes
      type: object
      properties:
        id:
          description: Internal report id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: rp_01hz1f0kw36f82k9s4nzpc4s92n
        uri:
          format: uri
          type: string
        comment:
          type: string
        fromUserId:
          description: User who reported the content
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        targetPostIds:
          description: Posts that were reported
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
          example:
            - pt_01hz1f0jkdw3h27a2kdr8sn2kt
          nullable: true
        targetUserId:
          description: User who was reported
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        groupId:
          description: |2-

                    Report scope.
                    If empty the scope is global.
                    If set the scope is group and group admins can take actions
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        createdAt:
          $ref: '#/components/schemas/Instant'
        updatedAt:
          $ref: '#/components/schemas/Instant'
        assignedUser:
          description: Moderator assigned to handle the report
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: us_01hz1fkfg82hf89s2nzqwer02r
          nullable: true
        actionTakenAt:
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        actionTakenBy:
          description: Moderator who took action on the report
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: us_01hz1fkfg82hf89s2nzqwer02r
          nullable: true
        forwarded:
          type: boolean
        notes:
          type: array
          items:
            $ref: '#/components/schemas/ReportNote'
        fromUser:
          allOf:
            - $ref: '#/components/schemas/User'
          nullable: true
        targetUser:
          allOf:
            - $ref: '#/components/schemas/User'
          nullable: true
        posts:
          type: array
          items:
            $ref: '#/components/schemas/Post'
          nullable: true
    ReportNote:
      required:
        - userId
        - note
        - createdAt
      type: object
      properties:
        userId:
          description: User who added the note
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        note:
          type: string
        createdAt:
          $ref: '#/components/schemas/Instant'
    ReportsPaginatedResponse:
      required:
        - list
      type: object
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/Report'
        total:
          format: int32
          type: integer
        offset:
          format: int32
          type: integer
          nullable: true
    RepostParam:
      description: |2-

                    Options for '?repostKind' param
                    * REPOST - repost only
                    * QUOTE - quote only
                    * ALL  - any, has the same effect as omitting the param
                    
      enum:
        - REPOST
        - QUOTE
        - ALL
      type: string
    ResourceModel:
      required:
        - name
        - description
        - actions
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        actions:
          type: array
          items:
            $ref: '#/components/schemas/ActionModel'
    RoleId:
      description: >-
        Fully qualified (scope:id) pre-defined role ID or UUID with type prefix
        'rr_' 
      type: string
      example: |2-

                'admin',
                'System:admin',
                'rr_01hxcvk1hjexere4pvtrj0ymqq',
                'System:rr_01hxcvk1hjexere4pvtrj0ymqq',
                'gr_1lkjvfdoibb126576:rr_01hxcvk1hjexere4pvtrj0ymqq',
            
    Route:
      required:
        - path
      type: object
      properties:
        path:
          type: string
        handler:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        entryPointFor:
          allOf:
            - $ref: '#/components/schemas/EntryPoint'
          nullable: true
        order:
          format: int32
          type: integer
        permissions:
          allOf:
            - $ref: '#/components/schemas/RoutePermissions'
          nullable: true
    RoutePermissions:
      type: object
      properties:
        anyOf:
          type: array
          items:
            $ref: '#/components/schemas/RBACResourceAccess'
          nullable: true
        allOf:
          type: array
          items:
            $ref: '#/components/schemas/RBACResourceAccess'
          nullable: true
    RpEntity:
      type: object
      properties:
        id:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
    Rule:
      description: >-
        A rule that governs member conduct and content policies within a group
        or platform. Rules help establish community guidelines and expected
        behavior standards.
      required:
        - text
        - hint
        - ordering
        - id
      type: object
      properties:
        text:
          description: >-
            The rule text that defines expected behavior or policy (max 500
            characters)
          maxLength: 500
          type: string
          example: Be respectful to all members
        hint:
          description: >-
            Additional context or clarification for the rule (max 500
            characters)
          maxLength: 500
          type: string
          example: >-
            This includes no harassment, personal attacks, or discriminatory
            language
        ordering:
          format: int32
          description: Display order position - rules with lower values appear first
          minimum: 0
          type: integer
          example: 1000
        id:
          description: Unique identifier for the rule
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: rl_01hz1f0gs9fe4a37jzvzn9m96k
    RuleCreate:
      description: >-
        Request payload for creating a new rule. Provide text, hint, and
        ordering.
      required:
        - text
        - hint
        - ordering
      type: object
      properties:
        text:
          description: >-
            The rule text that defines expected behavior or policy (max 500
            characters)
          maxLength: 500
          type: string
          example: Be respectful to all members
        hint:
          description: >-
            Additional context or clarification for the rule (max 500
            characters)
          maxLength: 500
          type: string
          example: >-
            This includes no harassment, personal attacks, or discriminatory
            language
        ordering:
          format: int32
          description: Display order position - rules with lower values appear first
          minimum: 0
          type: integer
          example: 1000
    RuleOrderingRequest:
      description: Request payload for updating a rule's display order position
      required:
        - id
        - ordering
      type: object
      properties:
        id:
          description: The unique identifier of the rule to reorder
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: rl_01hz1f0gs9fe4a37jzvzn9m96k
        ordering:
          format: int32
          description: New display order position (lower values appear first)
          minimum: 0
          type: integer
          example: 1000
    RuleUpdate:
      description: >-
        Request payload for updating an existing rule. All fields are required
        and will replace the current values. To maintain existing values,
        provide the current content.
      required:
        - text
        - hint
        - ordering
      type: object
      properties:
        text:
          description: >-
            The rule text that defines expected behavior or policy (max 500
            characters)
          maxLength: 500
          type: string
          example: Be respectful to all members
        hint:
          description: >-
            Additional context or clarification for the rule (max 500
            characters)
          maxLength: 500
          type: string
          example: >-
            This includes no harassment, personal attacks, or discriminatory
            language
        ordering:
          format: int32
          description: Display order position - rules with lower values appear first
          minimum: 0
          type: integer
          example: 1000
    Salary:
      description: Salary data
      required:
        - min
        - max
        - currency
        - payType
      type: object
      properties:
        min:
          format: double
          description: The lower boundary of the salary range
          maximum: 10000000
          minimum: 0
          type: number
          nullable: true
        max:
          format: double
          description: The upper boundary of the salary range
          maximum: 10000000
          minimum: 0
          type: number
          nullable: true
        currency:
          description: The currency in which the salary is paid
          maxLength: 64
          type: string
          example: USD, EURO...
          nullable: true
        payType:
          description: The pay type/period
          maxLength: 128
          type: string
          example: Hourly, Weekly, Annually
          nullable: true
    SearchDetails:
      description: Search results for users
      required:
        - list
        - total
        - totalUsers
      type: object
      properties:
        list:
          description: List of user details matching the search criteria
          type: array
          items:
            $ref: '#/components/schemas/UserDetails'
        total:
          format: int32
          description: Total number of results for the current search
          type: integer
        totalUsers:
          format: int32
          description: Total number of users in the system
          type: integer
    SearchFilter:
      enum:
        - users
        - posts
        - tags
        - events
        - groups
      type: string
    SearchResult:
      required:
        - users
        - posts
        - tags
        - events
        - groups
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserFull'
        posts:
          type: array
          items:
            $ref: '#/components/schemas/Post'
        tags:
          type: array
          items:
            type: string
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
        groups:
          type: array
          items:
            $ref: '#/components/schemas/Group'
    ServerInfo:
      required:
        - followers
        - followings
        - reports
        - available
        - failureDays
        - failureThreshold
      type: object
      properties:
        users:
          format: int64
          type: integer
        posts:
          format: int64
          type: integer
        followers:
          format: int64
          description: N of remote users who are being followed from this server
          type: integer
        followings:
          format: int64
          description: N of local users who follow users on this domain
          type: integer
        reports:
          format: int32
          description: N of reports against users of this domain
          type: integer
        available:
          description: Whether it's whitelisted when limited federation mode is on
          type: boolean
        failureDays:
          format: int32
          description: N of days federation has been unavailable for this domain
          type: integer
        failureThreshold:
          format: double
          description: Duration in seconds
          type: number
          allOf:
            - $ref: '#/components/schemas/Duration'
        blocked:
          allOf:
            - $ref: '#/components/schemas/BlockedDomain'
          nullable: true
    ServerTotals:
      description: Current server totals for users and posts
      required:
        - users
        - localPosts
        - remotePosts
        - groups
        - localComments
        - remoteComments
        - updatedAt
      type: object
      properties:
        users:
          format: int64
          description: Total number of users on the server
          type: integer
        localPosts:
          format: int64
          description: Total number of local posts on the server
          type: integer
        remotePosts:
          format: int64
          description: Total number of remote posts on the server
          type: integer
        groups:
          format: int64
          description: Total number of groups on the server
          type: integer
        localComments:
          format: int64
          description: Total number of local comments on the server
          type: integer
        remoteComments:
          format: int64
          description: Total number of remote comments on the server
          type: integer
        updatedAt:
          description: Last updated timestamp
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
    ServersResult:
      required:
        - list
        - failureThreshold
      type: object
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/ServersResultInfo'
        total:
          format: int32
          type: integer
        failureThreshold:
          format: double
          description: Duration in seconds
          type: number
          allOf:
            - $ref: '#/components/schemas/Duration'
    ServersResultInfo:
      required:
        - domain
        - failureDays
        - allowed
      type: object
      properties:
        domain:
          type: string
        users:
          format: int64
          type: integer
        failureDays:
          format: int32
          description: N of days federation has been unavailable for this domain
          type: integer
        available:
          type: boolean
        allowed:
          description: Whether it's whitelisted when limited federation mode is on
          type: boolean
        blocked:
          allOf:
            - $ref: '#/components/schemas/DomainBlockState'
          nullable: true
        reports:
          format: int32
          type: integer
        rejectMedia:
          description: Whether media files from this domain are rejected
          type: boolean
          nullable: true
        rejectReports:
          description: Whether reports from this domain are rejected
          type: boolean
          nullable: true
    SessionExtra:
      type: object
      properties:
        userAgent:
          type: string
          nullable: true
        os:
          type: string
          nullable: true
    SessionInfo:
      required:
        - sessionKey
        - state
        - accountId
        - userId
        - loginType
        - ip
        - createdAt
        - extra
      type: object
      properties:
        sessionKey:
          type: string
        state:
          $ref: '#/components/schemas/SessionState'
        accountId:
          $ref: '#/components/schemas/TypeId'
        userId:
          $ref: '#/components/schemas/TypeId'
        loginType:
          $ref: '#/components/schemas/LoginType'
        ip:
          $ref: '#/components/schemas/InetAddress'
        createdAt:
          $ref: '#/components/schemas/Instant'
        countryCode:
          type: string
          nullable: true
        countryName:
          type: string
          nullable: true
        subdivision:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        extra:
          $ref: '#/components/schemas/SessionExtra'
        lastUsed:
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
    SessionState:
      enum:
        - ACTIVE
        - EXPIRED
      type: string
    SignupInviteLink:
      description: Invite link for user signups
      required:
        - code
        - ownerUserId
        - maxUses
        - usedCount
        - active
        - createdAt
        - accounts
      type: object
      properties:
        code:
          description: Unique invite code
          type: string
        ownerUserId:
          description: Owner user id who created the link
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        expiresAt:
          description: Expiration timestamp (UTC)
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        maxUses:
          format: int32
          description: Maximum number of uses
          type: integer
        usedCount:
          format: int32
          description: Number of uses so far
          type: integer
        active:
          description: Whether link is active (not deactivated)
          type: boolean
        createdAt:
          description: Creation timestamp (UTC)
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
        deactivatedAt:
          description: Deactivation timestamp (UTC)
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        accounts:
          description: List of account IDs created using this link
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
    SignupInviteLinkCreate:
      description: Create a signup invite link
      required:
        - maxUses
      type: object
      properties:
        expiresAt:
          description: Expiration timestamp (UTC)
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        maxUses:
          format: int32
          description: Maximum number of uses
          type: integer
          example: 3
    SignupInviteLinkList:
      description: Paginated list of signup invite links
      required:
        - links
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/SignupInviteLink'
        total:
          format: int32
          type: integer
    SignupReasonParams:
      description: Reason for signing up for admin approval
      required:
        - hash
        - reason
      type: object
      properties:
        hash:
          description: Registration hash
          pattern: \S
          type: string
          example: aaaaaaa-ccccccccccccc-wwwwwwwww
        reason:
          description: Reason for signing up for admin approval
          maxLength: 1024
          pattern: \S
          type: string
    SignupRequest:
      required:
        - hash
        - username
        - displayName
        - password
        - confirmationType
        - reason
        - ip
        - userAgent
        - createdAt
      type: object
      properties:
        hash:
          description: Unique hash for the signup request
          type: string
          example: hash123
        email:
          description: Email address for the account
          type: string
          example: john@example.com
          nullable: true
        phone:
          description: Phone number for the account
          type: string
          example: '+12345678901'
          nullable: true
        username:
          description: Username for the first user
          type: string
          example: john_smith
        displayName:
          description: Display name for the first user
          maxLength: 56
          minLength: 1
          type: string
          example: John Smith
        password:
          description: Account password, enforced by password policy
          type: string
          example: PassW0rd!
          nullable: true
        confirmationType:
          description: Current step in the signup flow
          type: string
          allOf:
            - $ref: '#/components/schemas/SignupRequestStep'
          example: EMAIL
        reason:
          description: Reason for creating account
          type: string
          example: Reason for signup
        ip:
          description: IP address of the user
          type: object
          allOf:
            - $ref: '#/components/schemas/InetAddress'
        userAgent:
          description: User agent of the user
          type: string
          example: Mozilla/5.0
        geoData:
          description: Geolocation data of the user
          type: object
          allOf:
            - $ref: '#/components/schemas/GeoData'
          nullable: true
        createdAt:
          description: Creation timestamp of the request
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2023-01-01T00:00:00Z'
        inviteCode:
          description: Invite code if provided
          type: string
          example: abcd-efgh-1234
          nullable: true
    SignupRequestResult:
      required:
        - list
        - total
      type: object
      properties:
        list:
          description: List of signup requests
          type: array
          items:
            $ref: '#/components/schemas/SignupRequest'
        total:
          format: int32
          description: Total number of signup requests matching the query
          type: integer
          example: 42
    SignupRequestStep:
      description: |2-

            Shows the current step in the signup flow:
               * EMAIL – We sent an email to the user with a verification code. The user must enter the code
                         to confirm their email.
               * PHONE – We sent a text to the user with a verification code. The user must enter the code
                         to confirm their phone number.
               * CAPTCHA – The user must complete a CAPTCHA verification.
               * REASON – The user must provide a reason for admins to approve their signup request.
               * ADMIN – Admins must approve or reject the user's signup request. No action is required from the user.
               * USER – The final step that creates the account. Most of the time, no action is required from the user.
                        If the account can't be created because the username is already taken, the user can
                        provide a different username at this step.
            
      enum:
        - EMAIL
        - PHONE
        - CAPTCHA
        - REASON
        - ADMIN
        - USER
      type: string
    SlidingWindowMetrics:
      description: |2-

                Wall-clock aligned tumbling window metrics for monitoring operation performance over time periods.

                **Key Features:**
                - Windows are aligned to wall-clock boundaries (e.g., 10:00-10:10, 10:10-10:20)
                - All operations share the same window boundaries for consistent comparison
                - Windows reset completely when they expire (tumbling, not sliding)
                - Memory-efficient with constant storage per operation per window

                **Synchronous Boundaries:** All operations use identical window start/end times
                ```
                10:05 - "follow" metric     → Window: 10:00-10:10
                10:07 - "create-note" metric → Window: 10:00-10:10 (same window)
                10:11 - "follow" metric     → Window: 10:10-10:20 (new window)
                ```

                **Complete Reset on Expiration:**
                ```
                Window 10:00-10:10: follow(avg=150ms, count=45)
                Window 10:10-10:20: follow(avg=200ms, count=12) ← Fresh start
                ```

                **Gap Handling:**
                ```
                10:05 - Metrics recorded → Window: 10:00-10:10
                [No activity for 25 minutes]
                10:35 - New metric      → Window: 10:30-10:40 ← Fresh window
                ```
                Previous windows (10:10-10:20, 10:20-10:30) remain empty/non-existent.

                **Limitations:**
                - **Not true sliding**: Old data is completely lost when windows expire
                - **Coarse granularity**: Only shows averages per window, not sub-window patterns
                - **No historical depth**: Only current window data is retained

                **UI Display Recommendations:**
                ```
                "Follow operations: 150ms avg (45 ops, 10:00-10:10, last updated 10:08:30)"
                ```
                Use windowCreated and lastUpdated to show clear time boundaries and data freshness.
            
      required:
        - average
        - count
        - totalTime
        - lastUpdated
        - operation
        - windowCreated
      type: object
      properties:
        average:
          format: double
          description: Average duration in milliseconds for operations in this window
          type: number
        count:
          format: int64
          description: Total number of operations recorded in this window
          type: integer
        totalTime:
          format: int64
          description: Sum of all operation durations in milliseconds
          type: integer
        lastUpdated:
          description: When the last metric was added to this window
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
        operation:
          description: The operation name being tracked
          type: string
        windowCreated:
          description: When this window was created (first metric timestamp)
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
    SlowestOperationsResponse:
      required:
        - slowestOperations
      type: object
      properties:
        slowestOperations:
          type: array
          items:
            $ref: '#/components/schemas/GlobalAggregatedMetrics'
        totalOperationsAnalyzed:
          format: int32
          type: integer
    SlowestUsersResponse:
      required:
        - slowestUsers
        - ownerType
      type: object
      properties:
        slowestUsers:
          type: array
          items:
            $ref: '#/components/schemas/UserMetrics'
        ownerType:
          $ref: '#/components/schemas/PostOwnerType'
        operation:
          allOf:
            - $ref: '#/components/schemas/FeedOperation'
          nullable: true
        limit:
          format: int32
          type: integer
    SortOrder:
      description: |2-

              Sort order for query results:
              * ASC - Ascending order (smallest to largest, oldest to newest)
              * DESC - Descending order (largest to smallest, newest to oldest)
               
      enum:
        - ASC
        - DESC
      type: string
    StreamingData:
      description: |-
        Incoming message from a websocket subscription. Streamable API.
               `data` can be User, Post, Notification depending on the type and context.
               
      required:
        - type
        - topic
      type: object
      properties:
        type:
          $ref: '#/components/schemas/StreamingType'
        topic:
          type: string
        data:
          oneOf:
            - $ref: '#/components/schemas/Post'
            - $ref: '#/components/schemas/UserFull'
            - $ref: '#/components/schemas/TypeId'
            - $ref: '#/components/schemas/Notification'
        meta:
          type: object
          additionalProperties: {}
          nullable: true
    StreamingType:
      description: |2-

            Type of the incoming websocket message.
            dictionary:
              * POST_NEW - feed:* topics new post, add to the feed, check sorting. `data` is Post.
              * POST_UPDATE - post:* and feed:* topics. If topic is feed, update inside the feed. `data` is Post.
              * POST_REMOVE - feed:* topics. `data` is TypeId (postId)
              * REPOST - post: and feed: topics. `data` Post (repost/quote with originalPost as repostOf)
              * LIKE - post:* and feed:* topics. `data` is Post with the new likes count.
              * COMMENT - post:* and feed:* topics. `data` is Post (comment with originalPost as replyTo)
              * COMMENT_REMOVE - post:* and feed:* topics. `data` is TypeId (comment ID)
              * USER_UPDATE - user:* topic, updated user data. `data` is UserView
              * USER_REMOVE - user:* topic, updated user data. `data` is TypeId (userId)
              * ACCOUNT - account:* topic, updated account data. `data` is AccountWithUser
              * NOTIFICATION - notification:* topic, new notification. `data` is Notification
              * NOTIFICATION_UNDO - notification:* topic, removed notifications. `data` is TypeId (notificationId)
              * EVENT_NEW - events:* topics, new event. `data` is Event
              * EVENT_UPDATE - event:* and events:* topics, updated event. `data` is Event
              * EVENT_CANCEL - event:* and events:* topics, cancelled event. `data` is Event
              * EVENT_ATTENDEES - event:* and events:* topics, updated attendees or join/interest. `data` is Event
              * EVENT_DELETE - event:* and events:* topics, deleted event. `data` is TypeId (eventId)
               
      enum:
        - POST_NEW
        - POST_UPDATE
        - POST_REMOVE
        - REPOST
        - LIKE
        - COMMENT_NEW
        - COMMENT_UPDATE
        - COMMENT_REMOVE
        - USER_UPDATE
        - USER_REMOVE
        - ACCOUNT
        - NOTIFICATION
        - NOTIFICATION_UNDO
        - EVENT_NEW
        - EVENT_UPDATE
        - EVENT_CANCEL
        - EVENT_DELETE
        - EVENT_ATTENDEES
      type: string
    SupportedLanguage:
      required:
        - code
        - nativeName
      type: object
      properties:
        code:
          type: string
        nativeName:
          type: string
    Tag:
      required:
        - name
      type: object
      properties:
        name:
          type: string
        totalUses:
          format: int32
          type: integer
          nullable: true
        history:
          type: array
          items:
            $ref: '#/components/schemas/TagHistory'
          nullable: true
    TagHistory:
      required:
        - date
      type: object
      properties:
        uses:
          format: int32
          type: integer
        date:
          $ref: '#/components/schemas/LocalDate'
    TagPolicyMode:
      enum:
        - WHITELIST
        - BLACKLIST
      type: string
    TimeGranularity:
      description: Time granularity for metrics aggregation
      enum:
        - HOUR
        - DAY
        - MONTH
      type: string
    TimeZone:
      description: User's timezone preferences
      type: object
      properties:
        ianaTimezone:
          type: string
          nullable: true
        autoUpdate:
          type: boolean
        show:
          type: boolean
    TimezoneInfo:
      required:
        - value
        - abbr
        - text
        - utc
      type: object
      properties:
        value:
          type: string
        abbr:
          type: string
        offset:
          format: float
          type: number
        isdst:
          type: boolean
        text:
          type: string
        utc:
          type: array
          items:
            type: string
    Token:
      required:
        - sessionKey
      type: object
      properties:
        sessionKey:
          description: Persistent Token
          type: string
    TranslationRequest:
      required:
        - text
        - language
      type: object
      properties:
        text:
          type: string
        language:
          $ref: '#/components/schemas/Language'
        isHtml:
          type: boolean
    TranslationResponse:
      required:
        - text
      type: object
      properties:
        text:
          type: string
    UUID:
      format: uuid
      pattern: >-
        [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}
      type: string
    UpdateDraftRequest:
      type: object
      properties:
        text:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        privacy:
          allOf:
            - $ref: '#/components/schemas/PostPrivacy'
          nullable: true
        tags:
          type: array
          items:
            type: string
          nullable: true
        postId:
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        postAsOwner:
          type: boolean
          nullable: true
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
          nullable: true
    UpdateEvent:
      description: Event params that can be changed
      type: object
      properties:
        name:
          description: Event name
          type: string
          example: New Event Name
          nullable: true
        startTime:
          description: Event start time in UTC
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2024-02-18T15:00:00Z'
          nullable: true
        endTime:
          description: Event end time in UTC.
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          example: '2024-02-18T18:00:00Z'
          nullable: true
        ianaTimeZone:
          description: Event IANA time zone name
          type: string
          example: Europe/Paris
          nullable: true
        description:
          description: Event's description
          type: string
          example: This is a birthday party
          nullable: true
        url:
          format: uri
          description: Event URL
          type: string
          nullable: true
        address:
          description: Event address
          type: object
          allOf:
            - $ref: '#/components/schemas/AddressData'
          nullable: true
        imageId:
          description: Event cover image id.
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        removeEndTime:
          description: Remove event's endTime.
          type: boolean
        removeImage:
          description: Remove event's image.
          type: boolean
        removeAddress:
          description: Remove event's address.
          type: boolean
        removeDescription:
          description: Remove event's description.
          type: boolean
    UpdateEventsSettings:
      description: Events Settings update
      required:
        - exportPublicCalendar
        - exportPublicDetails
        - exportPublicEvents
        - exportPrivateCalendar
        - exportPrivateEvents
      type: object
      properties:
        exportPublicCalendar:
          description: Enable public calendar export
          type: boolean
        exportPublicDetails:
          description: Enable public calendar export with full event details
          type: boolean
        exportPublicEvents:
          description: Events to export in public calendar
          type: string
          allOf:
            - $ref: '#/components/schemas/ExportCalendarEvents'
        exportPrivateCalendar:
          description: Enable private calendar export
          type: boolean
        exportPrivateEvents:
          description: Events to export in private calendar
          type: string
          allOf:
            - $ref: '#/components/schemas/ExportCalendarEvents'
        exportPrivateCalendarUniqueId:
          description: Private calendar unique id
          type: string
          nullable: true
    UpdateUploadPrivacy:
      description: Update upload privacy request
      required:
        - privacy
      type: object
      properties:
        privacy:
          description: 'New privacy of the upload. Possible values: PUBLIC, PRIVATE, DIRECT.'
          type: string
          allOf:
            - $ref: '#/components/schemas/UploadPrivacy'
          example: PUBLIC
        allowedUsers:
          description: |2-

                    Can contain a list of users who are allowed to access the upload.
                    Works only for uploads with privacy set to DIRECT.
                    
          uniqueItems: true
          type: array
          items:
            type: string
          nullable: true
    Upload:
      description: Uploaded file
      required:
        - uploadId
        - userId
        - uploadType
        - meta
        - size
        - files
        - tags
        - createdAt
        - updatedAt
      type: object
      properties:
        uploadId:
          description: Internal id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: up_kjhwieuy2387928371
        userId:
          description: User id this upload belongs to
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: us_97234khddqdkuhqwij
        uploadType:
          description: Type of the upload
          type: string
          allOf:
            - $ref: '#/components/schemas/UploadType'
        meta:
          description: Meta data
          type: object
          allOf:
            - $ref: '#/components/schemas/Meta'
        size:
          format: int64
          description: Size in bytes of all the files in this upload
          type: integer
        files:
          description: List of all the files this upload has
          type: array
          items:
            $ref: '#/components/schemas/FileDesc'
        tags:
          description: List of tags attached to upload
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/UploadsTags'
        error:
          description: Upload processing error
          type: string
          nullable: true
        cached:
          description: true if cached
          type: boolean
        logs:
          description: Logs
          type: string
          nullable: true
        remote:
          description: true if this upload is remote
          type: boolean
        createdAt:
          $ref: '#/components/schemas/Instant'
        updatedAt:
          $ref: '#/components/schemas/Instant'
    UploadJobsQueue:
      enum:
        - Submitted
        - InProgress
        - Completed
      type: string
    UploadList:
      description: Upload list request
      required:
        - userId
        - tags
        - orderType
      type: object
      properties:
        userId:
          $ref: '#/components/schemas/TypeId'
        tags:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/UploadsTags'
        orderType:
          type: string
        page:
          format: int32
          type: integer
        limit:
          format: int32
          type: integer
    UploadPrivacy:
      enum:
        - Public
        - Private
        - Direct
      type: string
    UploadType:
      description: 'Upload type: IMAGE, VIDEO, AUDIO, DOCUMENT'
      enum:
        - VIDEO
        - IMAGE
        - AUDIO
        - DOCUMENT
        - OTHER
      type: string
      example: video
    UploadUsages:
      required:
        - posts
      type: object
      properties:
        posts:
          type: array
          items:
            $ref: '#/components/schemas/PostAttachment'
        avatars:
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
          nullable: true
        headers:
          type: array
          items:
            $ref: '#/components/schemas/TypeId'
          nullable: true
    UploadsTags:
      description: Tags attached to the upload
      enum:
        - Post
        - Avatar
        - Header
        - Album
        - Emoji
        - Event
      type: string
      example: $post
    User:
      description: |-
        One of account's users.
               Can be multiple per account
      required:
        - id
        - username
        - domain
        - displayName
        - uri
        - createdAt
        - state
      type: object
      properties:
        groupUserName:
          description: Name of the channel inside a group
          type: string
          nullable: true
        id:
          description: internal id of this user
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        username:
          description: unique user name
          type: string
          example: john_smith
        domain:
          description: user's domain, remote only, empty for local
          type: string
          example: wlsly1.net
        displayName:
          description: full name of the user
          type: string
          example: John Smith
        uri:
          format: uri
          description: URI of this user
          type: string
          example: https://wlsly1.net/users/john_smith
        avatar:
          description: User's avatar
          type: object
          allOf:
            - $ref: '#/components/schemas/Upload'
          nullable: true
        createdAt:
          $ref: '#/components/schemas/Instant'
        deleted:
          type: boolean
          nullable: true
        state:
          description: User's moderation state
          type: string
          allOf:
            - $ref: '#/components/schemas/UserState'
        relationship:
          description: Relationship with this user
          type: object
          allOf:
            - $ref: '#/components/schemas/Relationship'
          nullable: true
        channel:
          description: Whether this is a channel or a user
          type: boolean
        groupId:
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        groupPrivacy:
          allOf:
            - $ref: '#/components/schemas/GroupChannelPrivacy'
          nullable: true
        groupMain:
          type: boolean
          nullable: true
        groupDefault:
          type: boolean
          nullable: true
        actorType:
          description: Whether this user is a person, application or a service
          type: string
          allOf:
            - $ref: '#/components/schemas/ActorType'
          nullable: true
    UserCountResponse:
      required:
        - operation
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/FeedOperation'
        ownerType:
          allOf:
            - $ref: '#/components/schemas/PostOwnerType'
          nullable: true
        userCount:
          format: int64
          type: integer
    UserCreate:
      description: Params to create new user. Can be multiple per account
      required:
        - username
        - displayName
      type: object
      properties:
        username:
          description: Username
          type: string
          example: john_smith
        displayName:
          description: Display Name
          pattern: \S
          type: string
          example: John Smith
        summary:
          description: User's bio
          maxLength: 1024
          type: string
          example: I work in IT
          nullable: true
        avatarId:
          description: Avatar upload id or null to remove
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        headerId:
          description: Header upload id or null to remove
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        actorType:
          description: User's role
          type: string
          allOf:
            - $ref: '#/components/schemas/ActorType'
          example: USER
          nullable: true
        channel:
          description: Whether this user is a channel
          type: boolean
          example: false
    UserDetails:
      description: Detailed user information
      required:
        - userId
        - username
        - displayName
        - numPosts
        - numFollowers
        - createdAt
        - state
        - roles
      type: object
      properties:
        userId:
          description: Internal ID of this user
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        accountId:
          description: ID of the account this user belongs to, empty for remote users
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        username:
          description: Unique username
          type: string
          example: john_smith
        displayName:
          description: Full name of the user
          type: string
          example: John Smith
        email:
          description: User's email address
          type: string
          example: john@example.com
          nullable: true
        domain:
          description: User's domain, remote only, empty for local
          type: string
          example: domain.net
          nullable: true
        numPosts:
          format: int32
          description: Number of posts by this user
          type: integer
        numFollowers:
          format: int32
          description: Number of followers this user has
          type: integer
        createdAt:
          description: When this user was created
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
        deletedAt:
          description: When this user was deleted, if applicable
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        lastActive:
          description: When this user was last active
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
        lastIP:
          description: Last IP address used by this user
          type: object
          allOf:
            - $ref: '#/components/schemas/InetAddress'
          nullable: true
        lastGeoData:
          description: Last geo data from which this user accessed the system
          type: object
          allOf:
            - $ref: '#/components/schemas/GeoData'
          nullable: true
        state:
          description: User's moderation state
          type: string
          allOf:
            - $ref: '#/components/schemas/UserState'
        channel:
          description: Whether this is a channel or a user
          type: boolean
        groupId:
          description: Group id if this user is a group channel
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        roles:
          description: Roles assigned to this user
          type: array
          items:
            $ref: '#/components/schemas/UserRole'
        avatar:
          description: User's avatar
          type: object
          allOf:
            - $ref: '#/components/schemas/Upload'
          nullable: true
    UserDevice:
      required:
        - userId
        - deviceId
        - fcmToken
        - endpoint
        - p256dh
        - auth
        - platform
        - createdAt
        - updatedAt
      type: object
      properties:
        userId:
          description: User ID owning this device
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        deviceId:
          description: Unique device identifier from client (fid)
          type: string
        fcmToken:
          description: FCM token for the device
          type: string
        endpoint:
          description: Relay endpoint to deliver to FCM
          type: string
        p256dh:
          description: User public key for encrypted push
          type: string
        auth:
          description: User auth secret for encrypted push
          type: string
        platform:
          description: Client platform (e.g. android, ios, web)
          type: string
        device:
          description: Optional device description
          type: string
          nullable: true
        createdAt:
          $ref: '#/components/schemas/Instant'
        updatedAt:
          $ref: '#/components/schemas/Instant'
    UserEntity:
      type: object
      properties:
        id:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        displayName:
          type: string
          nullable: true
    UserField:
      required:
        - value
      type: object
      properties:
        value:
          type: string
        verifiedAt:
          allOf:
            - $ref: '#/components/schemas/Instant'
          nullable: true
    UserFull:
      description: |-
        One of account's users.
               Can be multiple per account
      required:
        - id
        - username
        - domain
        - displayName
        - summary
        - uri
        - stats
        - fields
        - createdAt
        - state
        - software
      type: object
      properties:
        groupUserName:
          description: Name of the channel inside a group
          type: string
          nullable: true
        id:
          description: internal id of this user
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        username:
          description: unique user name
          type: string
          example: john_smith
        domain:
          description: user's domain, remote only, empty for local
          type: string
          example: wlsly1.net
        displayName:
          description: full name of the user
          type: string
          example: John Smith
        summary:
          description: User's summary or bio
          type: string
          example: Pixels are my paint, code is my canvas, creativity is my brush.
        uri:
          format: uri
          description: URI of this user
          type: string
          example: https://wlsly1.net/users/john_smith
        stats:
          description: User stats
          type: object
          allOf:
            - $ref: '#/components/schemas/UserStats'
        fields:
          description: User fields
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UserField'
        avatar:
          description: User's avatar
          type: object
          allOf:
            - $ref: '#/components/schemas/Upload'
          nullable: true
        header:
          description: User's header
          type: object
          allOf:
            - $ref: '#/components/schemas/Upload'
          nullable: true
        createdAt:
          $ref: '#/components/schemas/Instant'
        deleted:
          type: boolean
          nullable: true
        state:
          description: User's moderation state
          type: string
          allOf:
            - $ref: '#/components/schemas/UserState'
        relationship:
          description: Relationship with this user
          type: object
          allOf:
            - $ref: '#/components/schemas/Relationship'
          nullable: true
        emojis:
          type: array
          items:
            $ref: '#/components/schemas/Emoji'
          nullable: true
        location:
          description: User's location, geo and name
          type: object
          allOf:
            - $ref: '#/components/schemas/Location'
          nullable: true
        timezone:
          description: User's timezone
          type: object
          allOf:
            - $ref: '#/components/schemas/TimeZone'
          nullable: true
        birthday:
          description: User's birthday
          type: object
          allOf:
            - $ref: '#/components/schemas/Birthday'
          nullable: true
        software:
          description: Software platform type (wellesley, mastodon, threads.net)
          type: string
          example: wellesley
        channel:
          description: is channel user
          type: boolean
        groupId:
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        groupPrivacy:
          allOf:
            - $ref: '#/components/schemas/GroupChannelPrivacy'
          nullable: true
        groupMain:
          type: boolean
          nullable: true
        groupDefault:
          type: boolean
          nullable: true
        actorType:
          description: Whether this user is a person, application or a service
          type: string
          allOf:
            - $ref: '#/components/schemas/ActorType'
          nullable: true
    UserGroupSummary:
      description: Minimal data for user's groups with sorting information
      required:
        - groupId
        - name
        - displayName
        - summary
        - meta
        - isOwner
        - canManage
        - createdAt
      type: object
      properties:
        groupId:
          description: ID of the group
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
        name:
          description: Name of the group
          type: string
        displayName:
          description: Display name of the group
          type: string
        summary:
          description: Description of the group
          type: string
        avatar:
          description: Avatar upload for the group
          type: object
          allOf:
            - $ref: '#/components/schemas/Upload'
          nullable: true
        header:
          description: Header/banner upload for the group
          type: object
          allOf:
            - $ref: '#/components/schemas/Upload'
          nullable: true
        meta:
          description: Group metadata including color
          type: object
          allOf:
            - $ref: '#/components/schemas/GroupMeta'
        pin:
          format: int32
          description: Pin order number if pinned (null if not pinned)
          type: integer
          nullable: true
        isOwner:
          description: Whether user is the owner of this group
          type: boolean
        canManage:
          description: Whether user can manage this group (OWNER, ADMIN, or MODERATOR)
          type: boolean
        role:
          description: User's role in this group (owner, admin, moderator, member, viewer)
          type: string
          nullable: true
        createdAt:
          description: When the group was created (for sorting)
          type: string
          allOf:
            - $ref: '#/components/schemas/Instant'
    UserListCreate:
      required:
        - name
      type: object
      properties:
        name:
          maxLength: 64
          minLength: 1
          type: string
        description:
          maxLength: 512
          type: string
          nullable: true
        icon:
          maxLength: 256
          type: string
          nullable: true
        private:
          type: boolean
        pinned:
          type: boolean
    UserLite:
      required:
        - id
        - displayName
        - username
        - domain
      type: object
      properties:
        id:
          $ref: '#/components/schemas/TypeId'
        displayName:
          type: string
        username:
          type: string
        domain:
          type: string
    UserMetrics:
      type: object
    UserNote:
      required:
        - ownerId
        - userId
        - text
      type: object
      properties:
        ownerId:
          $ref: '#/components/schemas/TypeId'
        userId:
          $ref: '#/components/schemas/TypeId'
        text:
          maxLength: 500
          minLength: 1
          type: string
    UserPerformanceMetrics:
      required:
        - userId
      type: object
      properties:
        userId:
          $ref: '#/components/schemas/TypeId'
        averageTime:
          format: double
          type: number
        totalMeasurements:
          format: int64
          type: integer
    UserRole:
      description: User role information
      required:
        - roleId
        - name
      type: object
      properties:
        roleId:
          description: Internal ID of this role
          type: string
        name:
          description: Name of the role
          type: string
          example: ADMIN
        description:
          description: The description of the role
          type: string
          example: The Admin role in the "system" scope
          nullable: true
    UserState:
      description: |2-

            Registration mode:
              * REGULAR - just regular state
              * SENSITIVE - all media attachments are flagged as sensitive, i.e. all user's posts should be marked as sensitive, old posts and all future ones.
              * LIMITED - all user's old and future posts should be set maximum to followers only unless user set it to direct himself. non-followers should not be notified, i.e. if user mentions non-follower we do not create notification.
              * SUSPENDED - User can login, but cannot do anything in his account except to read, cannot change anything, cannot create new posts or comments etc. All his posts are marked as deleted, but we do not delete them just yet. User is scheduled to be deleted in one month. During this month it is possible to restore it via admin.
               
      enum:
        - REGULAR
        - SENSITIVE
        - LIMITED
        - SUSPENDED
      type: string
    UserStats:
      description: User stats
      required:
        - posts
        - followers
        - following
        - followingHidden
        - totalStorageBytes
        - comments
      type: object
      properties:
        posts:
          format: int32
          description: number of posts
          type: integer
        followers:
          format: int32
          description: number of followers
          type: integer
        following:
          format: int32
          description: number of following
          type: integer
        followingHidden:
          description: privacy setting to hide followings
          type: boolean
        totalStorageBytes:
          format: int64
          description: total storage volume in bytes
          type: integer
        comments:
          format: int32
          description: number of comments
          type: integer
    UserStorage:
      description: User upload storage information, split by upload type
      type: object
      properties:
        video:
          format: int64
          type: integer
        image:
          format: int64
          type: integer
        audio:
          format: int64
          type: integer
        document:
          format: int64
          type: integer
        other:
          format: int64
          type: integer
    UserUpdate:
      description: Params to update user info
      required:
        - displayName
        - summary
        - fields
      type: object
      properties:
        displayName:
          description: Display Name
          pattern: \S
          type: string
          example: John Smith
        summary:
          description: User's bio
          maxLength: 1024
          type: string
          example: I work in IT
        avatarId:
          description: Avatar upload id or null to remove
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        headerId:
          description: Header upload id or null to remove
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        fields:
          description: User fields
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UserField'
        username:
          description: Username
          type: string
          example: john_smith
          nullable: true
        location:
          allOf:
            - $ref: '#/components/schemas/Location'
          nullable: true
        timezone:
          allOf:
            - $ref: '#/components/schemas/TimeZone'
          nullable: true
        birthday:
          allOf:
            - $ref: '#/components/schemas/Birthday'
          nullable: true
        channel:
          description: Whether this user is a channel
          type: boolean
          example: false
        actorType:
          description: Actor type - if not specified, actor type is not changed
          type: string
          allOf:
            - $ref: '#/components/schemas/ActorType'
          example: Person
          nullable: true
    UserUpdateMedia:
      description: Params to update user media
      type: object
      properties:
        avatarId:
          description: Avatar upload id or null to remove
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        headerId:
          description: Header upload id or null to remove
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
    UserView:
      required:
        - state
        - id
        - username
        - domain
        - displayName
        - uri
        - createdAt
      type: object
      properties:
        state:
          $ref: '#/components/schemas/UserState'
        actorType:
          description: Whether this user is a person, application or a service
          type: string
          allOf:
            - $ref: '#/components/schemas/ActorType'
          nullable: true
        channel:
          type: boolean
        groupId:
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        groupPrivacy:
          allOf:
            - $ref: '#/components/schemas/GroupChannelPrivacy'
          nullable: true
        groupUserName:
          description: Name of the channel inside a group
          type: string
          nullable: true
        groupMain:
          type: boolean
          nullable: true
        groupDefault:
          type: boolean
          nullable: true
        deleted:
          type: boolean
          nullable: true
        id:
          $ref: '#/components/schemas/TypeId'
        username:
          type: string
        domain:
          type: string
        displayName:
          type: string
        uri:
          format: uri
          type: string
        createdAt:
          $ref: '#/components/schemas/Instant'
        avatar:
          allOf:
            - $ref: '#/components/schemas/Upload'
          nullable: true
        relationship:
          allOf:
            - $ref: '#/components/schemas/Relationship'
          nullable: true
    UsernameCheck:
      type: object
      properties:
        exists:
          type: boolean
    UsernameHistories:
      required:
        - history
      type: object
      properties:
        history:
          type: array
          items:
            $ref: '#/components/schemas/UsernameHistory'
        maxRenames:
          format: int32
          type: integer
    UsernameHistory:
      required:
        - username
        - domain
        - createdAt
      type: object
      properties:
        username:
          type: string
        domain:
          type: string
        userId:
          allOf:
            - $ref: '#/components/schemas/TypeId'
          nullable: true
        createdAt:
          $ref: '#/components/schemas/Instant'
    UsersList:
      required:
        - id
        - userId
        - name
        - createdAt
        - updatedAt
        - users
      type: object
      properties:
        id:
          description: Internal list id
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: ul_01hz1f0kw36f82k9s4nzpc4s92n
        userId:
          description: Owner of the list
          type: string
          allOf:
            - $ref: '#/components/schemas/TypeId'
          example: us_01hz1fkfg82hf89s2nzqwer02r
        name:
          type: string
        description:
          type: string
          nullable: true
        icon:
          type: string
          nullable: true
        private:
          type: boolean
        pinned:
          type: boolean
        createdAt:
          $ref: '#/components/schemas/Instant'
        updatedAt:
          $ref: '#/components/schemas/Instant'
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
    WindowSize:
      description: >-
        The size of a time window. Accepted format example: 'TEN_MINUTES' or
        '10m'
      enum:
        - TEN_MINUTES
        - ONE_HOUR
        - TWENTY_FOUR_HOURS
      type: string
    AudioPolicy:
      type: object
      properties:
        extensions:
          description: Allowed audio file extensions
          type: array
          items:
            description: File extension
            type: object
            properties:
              value:
                type: string
        keepOriginal:
          description: Whether to keep the original audio file
          type: boolean
        maxSize:
          description: Maximum allowed audio file size in bytes
          type: integer
    AuthConfig:
      type: object
      properties:
        tokenKey:
          description: Token encryption key
          type: string
    CaptchaConfig:
      type: object
      properties:
        secretKey:
          description: hCaptcha Account secret key
          type: string
        siteKey:
          description: Sitekey if the same account is used on several sites
          type: string
    CaptchaClientConfig:
      type: object
      properties:
        siteKey:
          description: Sitekey if the same account is used on several sites
          type: string
    ConfirmationCodeConfigs:
      type: object
      properties:
        codeExpirationMinutes:
          description: Expiration time for confirmation code
          type: integer
        counterExpirationMinutes:
          description: >-
            Time duration after which the counter for unsuccessful attempts will
            be reset
          type: integer
        limitCheckAttempts:
          description: Maximum number of attempts to check confirmation code
          type: integer
        limitStoreAttempts:
          description: Maximum number of attempts to request confirmation code
          type: integer
    DocPolicy:
      type: object
      properties:
        extensions:
          description: Allowed doc file extensions
          type: array
          items:
            description: File extension
            type: object
            properties:
              value:
                type: string
        maxSize:
          description: Maximum allowed doc file size in bytes
          type: integer
    EmojiPolicyConfig:
      type: object
      properties:
        maxImageSize:
          description: Maximum allowed single emoji image size in bytes
          type: integer
        maxZipSize:
          description: Maximum allowed ZIP size in bytes for emoji import
          type: integer
    ImagePolicy:
      type: object
      properties:
        extensions:
          description: Allowed image file extensions
          type: array
          items:
            description: File extension
            type: object
            properties:
              value:
                type: string
        keepOriginal:
          description: Whether to keep the original image file
          type: boolean
        maxMatrix:
          description: Maximum allowed image matrix resolution (width * height)
          type: integer
        maxResolution:
          description: Maximum allowed image resolution in pixels at the longest side
          type: integer
        maxSize:
          description: Maximum allowed image file size in bytes
          type: integer
        resolutions:
          description: List of resolutions to convert the image to
          type: array
          items:
            type: integer
    InstanceAdmin:
      required:
        - email
        - name
        - username
      type: object
      properties:
        email:
          description: Email of the server admin
          type: string
        name:
          description: Name of the server admin
          type: string
        username:
          description: Username of the server admin
          type: string
    InstanceLegal:
      required:
        - privacyPolicy
        - termsOfUse
      type: object
      properties:
        privacyPolicy:
          description: Privacy policy text
          type: string
        termsOfUse:
          description: Terms of use text
          type: string
    LanguageDetectionConfig:
      type: object
      properties:
        key:
          description: Language detection key, depends on type
          type: string
        service:
          description: Language detection service type
          enum:
            - internal
            - detectlanguage
            - languagelayer
            - deepl
          type: string
    MediaCacheConfig:
      type: object
      properties:
        checkInterval:
          type: integer
        enabled:
          description: Whether media cache is enabled or not
          type: boolean
        limitPerRun:
          type: integer
        maxFileSize:
          description: Maximum size of a single cached media file in bytes
          type: integer
        maxTotalSize:
          description: Maximum total size of cached media in bytes
          type: integer
        singleRun:
          type: boolean
    OpenAIConfig:
      type: object
      properties:
        apiKey:
          type: string
        model:
          description: OpenAI model to use
          type: string
    PostsConfig:
      required:
        - max_characters
        - max_media_attachments
        - max_pins
      type: object
      properties:
        max_characters:
          description: Maximum post size in characters
          type: integer
        max_media_attachments:
          description: Maximum number of attachments in post
          type: integer
        max_pins:
          description: Maximum number of pinned posts
          type: integer
    RemoteLinkServiceConfig:
      type: object
      properties:
        url:
          type: object
          properties:
            scheme:
              type: string
            fragment:
              type: string
            authority:
              type: string
            userInfo:
              type: string
            host:
              type: string
            port:
              type: integer
            path:
              type: string
            query:
              type: string
            schemeSpecificPart:
              type: string
            hash:
              type: integer
            decodedUserInfo:
              type: string
            decodedAuthority:
              type: string
            decodedPath:
              type: string
            decodedQuery:
              type: string
            decodedFragment:
              type: string
            decodedSchemeSpecificPart:
              type: string
            string:
              type: string
    SmsConfig:
      type: object
      properties:
        countries:
          description: List of supported countries
          type: array
          items:
            type: string
          example: '[US,CA]'
        enabled:
          description: Enable SMS service
          default: 'false'
          type: boolean
        provider:
          description: SMS service provider to use
          type: string
    SmsConfigAwsSns:
      type: object
      properties:
        accessKey:
          type: string
        fromUS:
          type: string
        region:
          type: string
        secretKey:
          type: string
        senderId:
          type: string
    SmsConfigSinch:
      type: object
      properties:
        accessKey:
          type: string
        accessSecret:
          type: string
        fromUS:
          type: string
        projectId:
          type: string
    SmsConfigTwilio:
      type: object
      properties:
        accountSid:
          type: string
        authToken:
          type: string
        serviceSid:
          type: string
    TranslationConfig:
      type: object
      properties:
        enabled:
          description: Whether translation is enabled on this server or not
          type: boolean
    TranslationServiceConfig:
      type: object
      properties:
        key:
          description: Translation service key, depends on type
          type: string
        service:
          description: Translation service type
          enum:
            - none
            - deepl
          type: string
    ProviderConfig:
      type: object
      properties:
        baseUrl:
          type: object
          properties:
            scheme:
              type: string
            fragment:
              type: string
            authority:
              type: string
            userInfo:
              type: string
            host:
              type: string
            port:
              type: integer
            path:
              type: string
            query:
              type: string
            schemeSpecificPart:
              type: string
            hash:
              type: integer
            decodedUserInfo:
              type: string
            decodedAuthority:
              type: string
            decodedPath:
              type: string
            decodedQuery:
              type: string
            decodedFragment:
              type: string
            decodedSchemeSpecificPart:
              type: string
            string:
              type: string
        cdn:
          type: object
          properties:
            media:
              type: string
            static:
              type: string
        domain:
          type: string
        local:
          type: object
          properties:
            basePath:
              type: string
        localBasePath:
          type: object
        provider:
          type: object
        s3:
          type: object
          properties:
            accessKey:
              type: string
            buckets:
              type: object
              properties:
                media:
                  type: string
                static:
                  type: string
            endpoint:
              type: string
            presignedUrlExpiration:
              type: integer
            region:
              type: string
            s3Region:
              type: object
              properties:
                isGlobalRegion:
                  type: boolean
                id:
                  type: string
            secretKey:
              type: string
        scheme:
          enum:
            - http
            - https
          type: string
        uploadsBasePath:
          type: object
    UsernameReleaseConfig:
      type: object
      properties:
        enabled:
          description: Whether username release is enabled
          type: boolean
        releasePeriodDays:
          description: >-
            Days after which deleted local users are completely purged,
            releasing their usernames
          type: integer
    VideoPolicy:
      type: object
      properties:
        extensions:
          description: Allowed video file extensions
          type: array
          items:
            description: File extension
            type: object
            properties:
              value:
                type: string
        keepOriginal:
          description: Whether to keep the original video file
          type: boolean
        maxDuration:
          description: Maximum allowed video duration in seconds
          type: integer
        maxMatrix:
          description: Maximum allowed video matrix resolution (width * height)
          type: integer
        maxResolution:
          description: Maximum allowed video resolution in pixels at the longest side
          type: integer
        maxSize:
          description: Maximum allowed video file size in bytes
          type: integer
        resolutions:
          description: List of resolutions to convert the video to
          type: array
          items:
            type: integer
        streamingThreshold:
          description: Threshold in seconds to convert video to m3u8
          type: integer
    PlatformSettings:
      type: object
      properties:
        wellesley.access:
          $ref: '#/components/schemas/InstanceAccess'
        wellesley.uploads.policy.audio:
          $ref: '#/components/schemas/AudioPolicy'
        wellesley.admin.auth:
          $ref: '#/components/schemas/AuthConfig'
        wellesley.branding:
          $ref: '#/components/schemas/InstanceBranding'
        wellesley.admin.captcha:
          $ref: '#/components/schemas/CaptchaConfig'
        wellesley.captcha:
          $ref: '#/components/schemas/CaptchaClientConfig'
        wellesley.confirmationCode:
          $ref: '#/components/schemas/ConfirmationCodeConfigs'
        wellesley.uploads.policy.doc:
          $ref: '#/components/schemas/DocPolicy'
        wellesley.instance.domainBlocks:
          $ref: '#/components/schemas/InstanceDomainBlocksPolicy'
        wellesley.uploads.policy.emoji:
          $ref: '#/components/schemas/EmojiPolicyConfig'
        wellesley.uploads.policy.image:
          $ref: '#/components/schemas/ImagePolicy'
        wellesley.instance.admin:
          $ref: '#/components/schemas/InstanceAdmin'
        wellesley.instance.contacts:
          $ref: '#/components/schemas/InstanceContacts'
        wellesley.instance.legal:
          $ref: '#/components/schemas/InstanceLegal'
        wellesley.admin.language:
          $ref: '#/components/schemas/LanguageDetectionConfig'
        wellesley.admin.mediacache:
          $ref: '#/components/schemas/MediaCacheConfig'
        wellesley.admin.openai:
          $ref: '#/components/schemas/OpenAIConfig'
        wellesley.posts:
          $ref: '#/components/schemas/PostsConfig'
        wellesley.registration:
          $ref: '#/components/schemas/InstanceRegistration'
        wellesley.admin.link_service:
          $ref: '#/components/schemas/RemoteLinkServiceConfig'
        wellesley.admin.sms:
          $ref: '#/components/schemas/SmsConfig'
        wellesley.admin.sms.aws:
          $ref: '#/components/schemas/SmsConfigAwsSns'
        wellesley.admin.sms.sinch:
          $ref: '#/components/schemas/SmsConfigSinch'
        wellesley.admin.sms.twilio:
          $ref: '#/components/schemas/SmsConfigTwilio'
        wellesley.translation:
          $ref: '#/components/schemas/TranslationConfig'
        wellesley.admin.translation:
          $ref: '#/components/schemas/TranslationServiceConfig'
        wellesley.admin.uploads:
          $ref: '#/components/schemas/ProviderConfig'
        wellesley.username.release:
          $ref: '#/components/schemas/UsernameReleaseConfig'
        wellesley.uploads.policy.video:
          $ref: '#/components/schemas/VideoPolicy'
    FollowConfig:
      type: object
      properties:
        autoAccept:
          type: boolean
    NotificationPolicy:
      type: object
      properties:
        blockNewAccounts:
          type: boolean
        blockNonFollowers:
          type: boolean
        blockNonFollowing:
          type: boolean
        blockNonFollowingMessages:
          type: boolean
    NotificationPrefs:
      type: object
      properties:
        email:
          type: object
          properties:
            comment:
              type: boolean
            eventCancel:
              type: boolean
            eventInvite:
              type: boolean
            eventJoin:
              type: boolean
            eventUpdate:
              type: boolean
            follow:
              type: boolean
            followRequest:
              type: boolean
            groupInvite:
              type: boolean
            like:
              type: boolean
            listPostCreate:
              type: boolean
            mention:
              type: boolean
            mute:
              type: object
              properties:
                enabled:
                  type: boolean
                expiresAt:
                  type: object
                  properties:
                    seconds:
                      type: integer
                    nanos:
                      type: integer
            postUpdate:
              type: boolean
            repost:
              type: boolean
        push:
          type: object
          properties:
            comment:
              type: boolean
            eventCancel:
              type: boolean
            eventInvite:
              type: boolean
            eventJoin:
              type: boolean
            eventUpdate:
              type: boolean
            follow:
              type: boolean
            followRequest:
              type: boolean
            groupInvite:
              type: boolean
            like:
              type: boolean
            listPostCreate:
              type: boolean
            mention:
              type: boolean
            mute:
              type: object
              properties:
                enabled:
                  type: boolean
                expiresAt:
                  type: object
                  properties:
                    seconds:
                      type: integer
                    nanos:
                      type: integer
            postUpdate:
              type: boolean
            repost:
              type: boolean
        subscribeOnComment:
          type: boolean
        syncAcrossProfiles:
          type: boolean
    PrivacyConfig:
      type: object
      properties:
        discoverable:
          type: boolean
        showFollowers:
          type: boolean
        showGroups:
          type: boolean
        showProfilePage:
          type: boolean
        showPublicPosts:
          type: boolean
    UserTranslationConfig:
      type: object
      properties:
        excludedLanguages:
          description: List of languages not offered for translation
          type: array
          items:
            type: string
          example: '["DE"]'
        filter:
          description: Filter posts to show only in those languages
          type: array
          items:
            type: string
          example: '["EN", "FR"]'
        preferredLanguage:
          description: Language to translate posts to
          type: string
          example: EN
        primaryLanguage:
          description: Language to use in UI
          type: string
          example: EN
    UserSettings:
      type: object
      properties:
        user.follow:
          $ref: '#/components/schemas/FollowConfig'
        user.notifications.policy:
          $ref: '#/components/schemas/NotificationPolicy'
        user.notifications.prefs:
          $ref: '#/components/schemas/NotificationPrefs'
        user.privacy:
          $ref: '#/components/schemas/PrivacyConfig'
        user.translation:
          $ref: '#/components/schemas/UserTranslationConfig'
    GroupJoinQuestions:
      type: object
      properties:
        show:
          type: boolean
    MembershipConfig:
      type: object
      properties:
        allowMemberInvites:
          type: boolean
        approveInvites:
          type: boolean
        maxMembers:
          type: integer
    ModerationConfig:
      type: object
      properties:
        blockedWords:
          type: array
          items:
            type: string
        dailyPostLimit:
          type: integer
        moderateLinks:
          type: boolean
        moderatePosts:
          type: boolean
        slowModeEnabled:
          type: boolean
        slowModeInterval:
          type: integer
        spamFilter:
          type: boolean
    GroupPrivacyConfig:
      type: object
      properties:
        showMemberList:
          type: boolean
        showStats:
          type: boolean
    GroupSettings:
      type: object
      properties:
        group.join.questions:
          $ref: '#/components/schemas/GroupJoinQuestions'
        group.membership:
          $ref: '#/components/schemas/MembershipConfig'
        group.moderation:
          $ref: '#/components/schemas/ModerationConfig'
        group.privacy:
          $ref: '#/components/schemas/GroupPrivacyConfig'
    MemberDisplaySettings:
      type: object
      properties:
        customDisplayName:
          type: string
        showActivity:
          type: boolean
        showInMemberList:
          type: boolean
        showJoinDate:
          type: boolean
    MemberPreferences:
      type: object
      properties:
        emailNotifications:
          type: boolean
        notificationFrequency:
          type: string
        notifications:
          type: boolean
    GroupMemberSettings:
      type: object
      properties:
        group.member.display:
          $ref: '#/components/schemas/MemberDisplaySettings'
        group.member.preferences:
          $ref: '#/components/schemas/MemberPreferences'
    ApiError:
      required:
        - errorCode
        - message
      type: object
      properties:
        errorCode:
          description: Error code
          type: string
        message:
          description: Error message
          type: string
        docUrl:
          description: Link to documentation
          type: string
  securitySchemes:
    header:
      type: apiKey
      description: Authentication token
      name: Authorization
      in: header
openapi: 3.0.3
tags:
  - name: AI Agents
    description: Assign and list group AI agent assignments
  - name: Accounts
    description: >-
      Account management and authentication endpoints. Handles user
      registration, login flows (email/phone), profile management, and account
      lifecycle operations. Supports multi-step signup with email/SMS
      verification, CAPTCHA, and optional admin approval.
  - name: ActivityPub
    description: WebFinger endpoint for ActivityPub user discovery and federation
  - name: Addresses
    description: Endpoints for suggesting and validating physical addresses
  - name: Admin
    description: >-
      Development and testing endpoints for populating the database with test
      data
  - name: Admin Accounts
    description: >-
      Administrative endpoints for account and user management. Provides
      comprehensive tools for managing user accounts, including creation,
      deletion, role assignment, password management, state changes, and user
      impersonation for bot accounts.
  - name: Admin ActivityPub
    description: Administrative endpoints for ActivityPub
  - name: Admin Audit
    description: >-
      Administrative endpoints for viewing and managing audit logs. Provides
      comprehensive logging of all security-relevant actions performed in the
      system.
  - name: Admin Domain Blocks
    description: >-
      Administrative APIs for managing domain blocks. Provides endpoints to
      block specific domains with different severity levels (SUSPEND, LIMIT,
      NOOP), update existing blocks, unblock domains, and list currently blocked
      domains. Domain blocks prevent or limit federation with specified domains.
  - name: Admin Domains Allow List
    description: >-
      Administrative endpoints for managing domain allowlists. When domain
      allowlisting is enabled, only domains in this list can federate with the
      instance.
  - name: Admin Email Allow List
    description: >-
      Administrative endpoints for managing email domain allowlist used for
      registrations.
  - name: Admin Email Blocks
    description: >-
      Administrative APIs for managing email blocks to prevent unwanted signups.
      Supports blocking specific email addresses and entire domains. Email
      blocks are automatically normalized and checked during user registration.
  - name: Admin Federation Metrics
    description: >-
      Administrative endpoints for monitoring and managing federation with other
      ActivityPub instances. Provides metrics on connected domains, user counts,
      post statistics, and federation health monitoring.
  - name: Admin Feeds
    description: Administrative endpoints for managing user feeds and cache
  - name: Admin Groups
    description: Administrative endpoints for Groups management
  - name: Admin Init
    description: Administration endpoints for system initialization and updates
  - name: Admin Posts
    description: >-
      Administrative endpoints for managing posts. Provides moderation
      capabilities to delete posts that violate community guidelines or are part
      of reported content.
  - name: Admin Remote Link Service
    description: >-
      Configure a remote link preview service provider for fetching rich link
      previews
  - name: Admin Reports
    description: >-
      Administrative endpoints for managing user reports and moderation.
      Provides tools for reviewing, assigning, resolving, and annotating reports
      about users, posts, and groups. Supports workflow management with
      assignment, notes, and resolution tracking.
  - name: Admin Signup Requests
    description: >-
      Administrative endpoints for managing user signup requests. Provides tools
      for reviewing, approving, rejecting, and managing signup requests in
      moderation queue. Supports workflow for manual account approval when
      enabled.
  - name: Admin Uploads
    description: >-
      Administrative endpoints for managing file uploads and media storage.
      Provides tools for monitoring user storage usage, searching uploaded
      files, and managing upload processing jobs. Supports queue management for
      async upload processing workflows.
  - name: Aliases
    description: Endpoints for managing previous usernames and username aliases
  - name: Application Data
    description: >-
      Endpoints for managing application-specific data storage. Provides a
      flexible key-value storage system for applications to store custom data
      associated with users, groups, or the platform. Supports tagging,
      filtering, and ownership-based access control.
  - name: Applications
    description: Endpoints for serving and routing platform applications to users
  - name: Blocks
    description: >-
      User blocking functionality for preventing interaction with specific
      users. Blocking a user prevents them from following you, seeing your
      posts, or interacting with your content. Block operations are federated to
      remote servers when blocking remote users.
  - name: Categories
    description: Endpoints for managing forum-specific categories
  - name: Domain Blocks
    description: >-
      Public API for listing domains blocked by this instance. Visibility and
      reason details are controlled by platform settings.
  - name: Domain-blocks
    description: >-
      Endpoints for managing user-level domain blocks to filter content from
      specific servers
  - name: Drafts
    description: >-
      Endpoints for creating, reading, updating, and deleting drafts, as well as
      publishing them to posts
  - name: Email
    description: >-
      Email address management for user accounts. Provides secure email change
      workflow with verification codes, password confirmation, and notification
      system. All email changes require authentication and are logged for
      security.
  - name: Emoji
    description: >-
      Custom emoji management system for the platform. Supports creating,
      uploading, importing/exporting, searching, and deleting custom emojis.
      Emojis are automatically resized and optimized. Admin-only operations
      require Emojis.Manage permission.
  - name: Events
    description: Endpoints for creating, retrieving, and managing events and attendees
  - name: Events ActivityPub
    description: ActivityPub-compatible endpoint for events
  - name: Follow
    description: >-
      User follow relationship management. Handles following/unfollowing users,
      managing follow requests, and querying follower/followee relationships.
      Supports both local and remote (federated) users with ActivityPub protocol
      integration.
  - name: Forums
    description: >-
      Endpoints for managing discussion forums, including creation, retrieval,
      and deletion
  - name: Geo
    description: Endpoints for geographic location lookup and timezone services
  - name: Group Applications
    description: >-
      Endpoints for managing applications available to groups, including
      listing, adding, and removing group-specific applications
  - name: Group Channels
    description: >-
      API endpoints for managing channels within groups. Channels are
      specialized accounts that enable organized content distribution within
      groups. They support hierarchical organization with main and default
      channels, privacy controls inherited from parent groups, and both scoped
      (group-specific) and global usernames for discovery. Group administrators
      manage channels while members can follow them.
  - name: Group Member Settings
    description: >-
      Endpoints for managing member-specific settings within groups. These
      settings are personal to each group member and affect their individual
      experience within the group. Members can only access and modify their own
      settings within groups they belong to.
  - name: Group Members
    description: >-
      API endpoints for managing group membership. Provides functionality to
      add, update, and remove members from groups, as well as retrieve
      membership information. Supports both local and federated groups through
      ActivityPub protocol. Access control is enforced based on group privacy
      settings and user permissions.
  - name: Group Questions
    description: >-
      API endpoints for managing group entry questions. Groups can require
      prospective members to answer questions before joining. Questions support
      multiple types (text, single choice, multiple choice) and are used to
      screen members when the group's join mode is set to QUESTIONS. Answers are
      validated and generate a token that can be used during the join process.
  - name: Group Reports
    description: >-
      Group-scoped moderation reports. Allows group admins to review and resolve
      reports targeting their channels, forums, and events without global
      moderator access.
  - name: Group Rules
    description: >-
      API endpoints for managing community rules within groups. Rules define the
      expected conduct and content policies that members must follow. Each rule
      consists of text (the rule itself), a hint (explanation or context), and
      an ordering value for display sequence. Rules are scoped to specific
      groups and can be managed by users with appropriate permissions.
  - name: Group Settings
    description: >-
      Endpoints for managing group-specific settings and configuration options.
      These endpoints allow authorized group members to view, update, and delete
      settings that control group behavior, features, and customization options.
  - name: Groups
    description: >-
      API endpoints for managing groups within the Wellesley platform. Groups
      are community spaces that can be public or private, support forums, and
      have their own membership and permission systems. Groups can be federated
      via ActivityPub for cross-instance communication.
  - name: Import
    description: >-
      Endpoints for importing data from other platforms including followers,
      blocks, and mutes
  - name: Instance
    description: >-
      Server instance information and configuration. Provides metadata about the
      server, compatible domains, supported languages, timezones, and countries.
      All endpoints are publicly accessible without authentication.
  - name: Invites
    description: Endpoints for sending and managing user invitations
  - name: Jobs
    description: >-
      Endpoints for monitoring and managing background job queues, including
      statistics, job listings, and queue monitoring
  - name: Link Preview
    description: >-
      Link preview generation service for extracting and caching URL metadata.
      Provides rich preview cards with title, description, image, and other
      metadata for embedding in posts and messages. Supports OpenGraph and
      Twitter Card protocols.
  - name: Lists
    description: >-
      Endpoints for managing user lists for organizing and grouping followed
      accounts
  - name: Logins
    description: >-
      Endpoints for managing user login methods including email, password, and
      phone authentication
  - name: Metrics
    description: Endpoints for retrieving metrics and analytics data from the events stream
  - name: Mutes
    description: Endpoints for managing user mutes to hide content from specific users
  - name: Notes
    description: Endpoints for managing personal notes about other users
  - name: Notifications
    description: >-
      Endpoints for managing user notifications including retrieving, counting,
      and marking notifications as read or unread
  - name: Passkeys
    description: Passkey (WebAuthn) registration and authentication
  - name: Password
    description: >-
      Endpoints for password management including changing, resetting, and
      recovering passwords
  - name: Pins
    description: Endpoints for pinning posts to profiles and retrieving pinned posts
  - name: Platform Data
    description: >-
      Endpoints for managing platform-wide and group-specific data storage.
      Unlike application data, this provides direct data management not tied to
      specific applications. Supports flexible ownership models including
      platform-level, group-level, and user-level data with appropriate access
      controls.
  - name: Platform Settings
    description: >-
      Endpoints for managing platform-wide settings and configuration options.
      These endpoints control server-level settings that affect the entire
      platform, including features, limits, security policies, and default
      behaviors for all users and groups.
  - name: Polls
    description: >-
      Endpoints for interacting with polls, including voting and retrieving
      results
  - name: Posts
    description: >-
      Endpoints for creating, reading, updating, and deleting posts, as well as
      managing comments, likes, bookmarks, and reposts
  - name: RBAC
    description: |2-

              Endpoints for retrieving Role-Based Access Control (RBAC) configurations and managing roles,
              resources, permissions and role-to-user assignments.
               Scoped Role Definition (`RBACRole`):
               - Represents roles within the RBAC system.
               - Each role has a unique `roleId`, a `name`, an optional `description`, and a `scope`.
               - The `scope` defines the domain or area in which the role is valid.
               - The `scope` can be Global (hardcoded), currently the only one is "System"
               - The `scope` also can be dynamic, currently we use Group Ids, like "gr_05hxcvk1hjexere4pvtrj0hggt"
               - Roles come with assigned permissions (`RBACPermissions`) that define what actions the role can perform on system resources.
               - Metadata such as `createdAt` and `updatedAt` timestamps track the role's lifecycle events.

               Permissions** (`RBACPermissions`):
               - Encapsulates resource-specific access controls.
               - Each permission object specifies the `resource` (e.g., "user", "document") and an associated list of allowed `RBACAccess` types.
               - `RBACAccess` enumerates the supported actions: `Read`, `Add`, `Modify`, `Delete`.

               Role Assignments to Actors (`RBACActorRole`):
               - Maps actors (e.g., users, services) to specific roles.
               - Tracks the association through `actorId` (representing the unique entity being assigned) and `roleId` (specific role ID).
               - Includes timestamps to record when the assignment was created or updated.
          
  - name: Remote collections
    description: API to retrieve followers and following collections for remote users.
  - name: Reports
    description: Endpoints for reporting content and managing content reports
  - name: Rules
    description: >-
      Endpoints for managing platform rules that govern user conduct and content
      policies
  - name: Search
    description: >-
      Endpoints for searching across users, posts, and tags with various
      filtering options
  - name: Sessions
    description: Endpoints for managing user authentication sessions and device logins
  - name: SignupInviteLinks
    description: Manage signup invite links
  - name: Tags
    description: >-
      Endpoints for managing hashtags, including following, featuring, and
      retrieving tag information
  - name: Tags v2
    description: Scoped tags search, policy lists and reports
  - name: Translation
    description: Endpoints for translating text between languages
  - name: Uploads
    description: Endpoints for uploading, retrieving, and managing media files
  - name: User Devices
    description: APIs for managing user devices for push notifications
  - name: User Settings
    description: >-
      Endpoints for managing user-specific settings and preferences. These
      endpoints allow authenticated users to view, update, and delete their
      personal settings that control their account behavior, interface
      preferences, privacy options, and feature customizations.
  - name: Users
    description: >-
      Endpoints for managing user profiles, including creation, retrieval,
      updates, and moderation
  - name: employee
    description: Employee. DO NOT USE, SUBJECT TO CHANGE/REMOVE
  - name: employer
    description: Employer. DO NOT USE, SUBJECT TO CHANGE/REMOVE
  - name: job-applications
    description: Jobs. DO NOT USE, SUBJECT TO CHANGE/REMOVE
  - name: job-postings
    description: Jobs. DO NOT USE, SUBJECT TO CHANGE/REMOVE
  - name: phone
    description: Phone management
paths:
  /api/v1/accounts/add-reason:
    post:
      summary: 'Signup - Step 4: Submit signup reason'
      description: >-
        Step 4 of signup (if required): collects reason for joining the
        platform. Used for manual approval workflows. Notifies admins of pending
        registration. Required when registration mode is set to approval-based.
      tags:
        - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignupReasonParams'
        required: true
      responses:
        '200':
          description: Registration hash and next step
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponse'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: RegistrationWrongState
                message: Wrong state
          description: Wrong state
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/accounts/authenticate/email:
    post:
      summary: Email/username authentication
      description: >-
        Authenticates using email address or username with password. Returns a
        session token for authenticated requests. The system automatically
        detects whether the login field is an email (contains @) or username.
        Updates last sign-in timestamp on successful authentication.
      tags:
        - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthRequest'
        required: true
      responses:
        '200':
          description: Account, all account users and session key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UserMissingCreds:
                  description: No credentials provided
                  value:
                    errorCode: UserMissingCreds
                    message: No credentials provided
                UserBadCreds:
                  description: Invalid user credentials provided
                  value:
                    errorCode: UserBadCreds
                    message: Invalid user credentials provided
          description: Unauthorized
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserError
                message: An unexpected user-related error
          description: An unexpected user-related error
      security: []
  /api/v1/accounts/authenticate/phone:
    post:
      summary: Phone number authentication
      description: >-
        Two-step phone authentication process. First call sends SMS code to the
        phone number. Second call with the code completes authentication and
        returns session token. Phone number must be registered to an existing
        account.
      tags:
        - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthPhoneRequest'
        required: true
      responses:
        '200':
          description: Session key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                VerificationCodeError:
                  description: Incorrect verification code
                  value:
                    errorCode: VerificationCodeError
                    message: Incorrect verification code
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
                SendSMSError:
                  description: Failed to send sms
                  value:
                    errorCode: SendSMSError
                    message: Failed to send sms
                InvalidPhoneNumber:
                  description: The provided phone number is invalid
                  value:
                    errorCode: InvalidPhoneNumber
                    message: The provided phone number is invalid
                SMSServiceDisabled:
                  description: SMS service is not enabled
                  value:
                    errorCode: SMSServiceDisabled
                    message: SMS service is not enabled
                SMSUnsupportedCountry:
                  description: SMS service is not available in this country
                  value:
                    errorCode: SMSUnsupportedCountry
                    message: SMS service is not available in this country
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserMissingCreds
                message: No credentials provided
          description: No credentials provided
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/accounts/change/name:
    put:
      summary: Change user display name
      description: >-
        Updates the display name for a specific user in the account. Can only
        change names for users belonging to the authenticated account. Specify
        user by either username or user ID. Changes are immediately reflected
        and streamed to connected clients.
      tags:
        - Accounts
      parameters:
        - description: id
          required: false
          name: id
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: name
          required: true
          name: name
          in: query
          schema:
            type: string
        - description: username
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: OK
          content:
            text/plain: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserIdOrUserNameMissing
                message: The userId or userName must be provided
          description: The userId or userName must be provided
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: CantChangeNameOtherUser
                message: Cannot change the name of another user
          description: Cannot change the name of another user
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security:
        - header: []
  /api/v1/accounts/check-captcha:
    post:
      summary: Verify CAPTCHA challenge
      description: >-
        Step 3 of signup (if enabled): validates CAPTCHA to prevent automated
        signups. Uses IP address for additional validation. Advances to next
        step on success. Skip if CAPTCHA is disabled in config.
      tags:
        - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaptchaVerificationParams'
        required: true
      responses:
        '200':
          description: Registration hash and next step
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponse'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                CaptchaError:
                  description: Incorrect captcha
                  value:
                    errorCode: CaptchaError
                    message: Incorrect captcha
                RegistrationWrongState:
                  description: Wrong state
                  value:
                    errorCode: RegistrationWrongState
                    message: Wrong state
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/accounts/confirm-email:
    post:
      summary: 'Signup - Step 2: Verify email with code'
      description: >-
        Step 2 of email signup: validates the confirmation code sent to email.
        Advances registration to next step (CAPTCHA, reason, or account
        creation). Code expires after a set time and has limited retry attempts.
      tags:
        - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CodeVerificationParams'
        required: true
      responses:
        '200':
          description: Registration hash and next step
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponse'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                RegistrationWrongState:
                  description: Wrong state
                  value:
                    errorCode: RegistrationWrongState
                    message: Wrong state
                VerificationCodeError:
                  description: Incorrect verification code
                  value:
                    errorCode: VerificationCodeError
                    message: Incorrect verification code
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/accounts/confirm-phone:
    post:
      summary: 'Signup - Step 2: Verify phone with code'
      description: >-
        Step 2 of phone signup: validates the SMS code sent to phone number.
        Advances registration to next step (CAPTCHA, reason, or account
        creation). Code expires after a set time and has limited retry attempts.
      tags:
        - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CodeVerificationParams'
        required: true
      responses:
        '200':
          description: Registration hash and next step
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponse'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                RegistrationWrongState:
                  description: Wrong state
                  value:
                    errorCode: RegistrationWrongState
                    message: Wrong state
                VerificationCodeError:
                  description: Incorrect verification code
                  value:
                    errorCode: VerificationCodeError
                    message: Incorrect verification code
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/accounts/delete:
    delete:
      summary: Delete current account
      description: >-
        Permanently deletes the authenticated account and all associated users.
        Sends deletion notifications to federated followers. Cannot delete if
        it's the last admin account on the server. This operation is
        irreversible - all data including posts, follows, and media will be
        removed.
      tags:
        - Accounts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: CantRemoveLastAdmin
                message: Cannot remove the last remaining admin user
          description: Cannot remove the last remaining admin user
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountIsNotRemoved
                message: Failed to remove the account
          description: Failed to remove the account
      security:
        - header: []
  /api/v1/accounts/email/change/confirm:
    post:
      summary: Confirm and complete email change
      description: >-
        Completes the email change process by verifying the confirmation code.
        Updates the account's email address upon successful verification. Sends
        confirmation to the new email address. Invalidates all existing tokens
        except the current session for security. The change is logged in the
        audit trail.
      tags:
        - Email
      requestBody:
        content:
          text/plain:
            schema:
              format: int32
              type: integer
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                VerificationCodeError:
                  description: Incorrect verification code
                  value:
                    errorCode: VerificationCodeError
                    message: Incorrect verification code
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
                EmailChangeRequestNotFound:
                  description: Request to change email not found
                  value:
                    errorCode: EmailChangeRequestNotFound
                    message: Request to change email not found
                EmailNotUpdated:
                  description: Failed to update the email address
                  value:
                    errorCode: EmailNotUpdated
                    message: Failed to update the email address
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EmailExists
                message: The email address is already associated with an account
          description: The email address is already associated with an account
      security:
        - header: []
  /api/v1/accounts/email/change/request:
    post:
      summary: Request email address change
      description: >-
        Initiates email change process for the authenticated account. Requires
        current password verification for security. Sends notification to
        current email and verification code to new email. The new email must not
        already be registered. Includes IP address and geolocation in
        notification for security awareness.
      tags:
        - Email
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailChangeRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: VerificationCodeTooMany
                message: Too many attempts
          description: Too many attempts
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserIncorrectPassword
                message: Invalid password provided
          description: Invalid password provided
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EmailExists
                message: The email address is already associated with an account
          description: The email address is already associated with an account
      security:
        - header: []
  /api/v1/accounts/email/change/resend-code:
    put:
      summary: Resend email verification code
      description: >-
        Resends the verification code to the new email address for a pending
        email change. Use when the initial code was not received or has expired.
        Rate limited to prevent abuse. Requires an active email change request.
      tags:
        - Email
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
                EmailChangeRequestNotFound:
                  description: Request to change email not found
                  value:
                    errorCode: EmailChangeRequestNotFound
                    message: Request to change email not found
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/accounts/finish-creating:
    post:
      summary: 'Signup - Final Step: Complete account creation'
      description: >-
        Final step of signup: creates the account and user after all validations
        pass. Returns account details with authentication token for immediate
        login. Sends welcome email if applicable. Can optionally update username
        at this stage.
      tags:
        - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinishCreatingAccountParams'
        required: true
      responses:
        '200':
          description: Account, users and session key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountWithUserAndToken'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                RegistrationApprovalRequired:
                  description: Registration approval required
                  value:
                    errorCode: RegistrationApprovalRequired
                    message: Registration approval required
                InvitesNotEnabled:
                  description: Invite links are not enabled
                  value:
                    errorCode: InvitesNotEnabled
                    message: Invite links are not enabled
                InvalidInviteCode:
                  description: Invalid or exhausted invite code
                  value:
                    errorCode: InvalidInviteCode
                    message: Invalid or exhausted invite code
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UserNameIsReserved:
                  description: The username is reserved and cannot be used
                  value:
                    errorCode: UserNameIsReserved
                    message: The username is reserved and cannot be used
                UserNameExists:
                  description: The username is already in use
                  value:
                    errorCode: UserNameExists
                    message: The username is already in use
                EmailExists:
                  description: The email address is already associated with an account
                  value:
                    errorCode: EmailExists
                    message: The email address is already associated with an account
                PhoneExists:
                  description: This phone number is already associated with an account
                  value:
                    errorCode: PhoneExists
                    message: This phone number is already associated with an account
          description: Conflict
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountCreationError
                message: Failed to create the account
          description: Failed to create the account
      security: []
      parameters:
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
  /api/v1/accounts/get-token/{hash}:
    put:
      summary: Retrieve token for approved phone account
      description: >-
        One-time token retrieval for phone-based accounts approved by admin.
        Used when admin manually approves a phone registration. The signup
        request is deleted after successful token generation. Only works for
        accounts in USER step of registration.
      tags:
        - Accounts
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Session key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: RegistrationWrongState
                message: Wrong state
          description: Wrong state
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/accounts/logins/add-email-password:
    post:
      summary: Request to add email/password to account
      description: >-
        Initiates the process of adding email and password authentication to an
        existing account. A confirmation code will be sent to the provided email
        address.
      tags:
        - Logins
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddEmailRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                EmailAlreadySet:
                  description: Email is already set for this account
                  value:
                    errorCode: EmailAlreadySet
                    message: Email is already set for this account
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EmailExists
                message: The email address is already associated with an account
          description: The email address is already associated with an account
      security:
        - header: []
  /api/v1/accounts/logins/add-email-password/confirm:
    post:
      summary: Confirm email/password addition
      description: >-
        Confirms the addition of email/password authentication by verifying the
        confirmation code sent to the email.
      tags:
        - Logins
      requestBody:
        content:
          text/plain:
            schema:
              format: int32
              type: integer
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                VerificationCodeError:
                  description: Incorrect verification code
                  value:
                    errorCode: VerificationCodeError
                    message: Incorrect verification code
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
                EmailChangeRequestNotFound:
                  description: Request to change email not found
                  value:
                    errorCode: EmailChangeRequestNotFound
                    message: Request to change email not found
                EmailAlreadySet:
                  description: Email is already set for this account
                  value:
                    errorCode: EmailAlreadySet
                    message: Email is already set for this account
                EmailNotUpdated:
                  description: Failed to update the email address
                  value:
                    errorCode: EmailNotUpdated
                    message: Failed to update the email address
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EmailExists
                message: The email address is already associated with an account
          description: The email address is already associated with an account
      security:
        - header: []
  /api/v1/accounts/logins/add-email-password/resend-code:
    put:
      summary: Resend email confirmation code
      description: >-
        Resends the confirmation code to the pending email address when adding
        email/password authentication.
      tags:
        - Logins
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: VerificationCodeTooMany
                message: Too many attempts
          description: Too many attempts
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/accounts/logins/add-phone:
    post:
      summary: Add phone number to account
      description: >-
        Adds phone number authentication to the account. If no code is provided,
        initiates SMS verification. If code is provided, confirms the phone
        number.
      tags:
        - Logins
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddPhoneRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                PhoneAlreadySet:
                  description: Phone number is already set for this account
                  value:
                    errorCode: PhoneAlreadySet
                    message: Phone number is already set for this account
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PhoneExists
                message: This phone number is already associated with an account
          description: This phone number is already associated with an account
      security:
        - header: []
  /api/v1/accounts/logins/remove-email-password:
    delete:
      summary: Remove email/password from account
      description: >-
        Removes email and password authentication method from the account.
        Cannot be removed if it's the last remaining login method.
      tags:
        - Logins
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EmailNotSet
                message: Email not set for this account
          description: Email not set for this account
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: CantRemoveLastLogin
                message: Cannot remove the last login option
          description: Cannot remove the last login option
      security:
        - header: []
  /api/v1/accounts/logins/remove-phone:
    delete:
      summary: Remove phone number from account
      description: >-
        Removes phone number authentication from the account. Cannot be removed
        if it's the last remaining login method.
      tags:
        - Logins
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PhoneNotSet
                message: Phone number not set for this account
          description: Phone number not set for this account
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: CantRemoveLastLogin
                message: Cannot remove the last login option
          description: Cannot remove the last login option
      security:
        - header: []
  /api/v1/accounts/password/change/confirm:
    post:
      summary: Changes password
      description: Changes password for current user
      tags:
        - Password
      requestBody:
        content:
          text/plain:
            schema:
              format: int32
              type: integer
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                VerificationCodeError:
                  description: Incorrect verification code
                  value:
                    errorCode: VerificationCodeError
                    message: Incorrect verification code
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
                PasswordNotUpdated:
                  description: Failed to change password
                  value:
                    errorCode: PasswordNotUpdated
                    message: Failed to change password
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/accounts/password/change/request:
    post:
      summary: Requests password change
      description: Requests password change for current user
      tags:
        - Password
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordChangeRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: VerificationCodeTooMany
                message: Too many attempts
          description: Too many attempts
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserIncorrectPassword
                message: Invalid password provided
          description: Invalid password provided
      security:
        - header: []
  /api/v1/accounts/password/change/resend-code:
    put:
      summary: Resends confirmation code to confirm new password for authenticated user
      description: Resends confirmation code to confirm new password for current user
      tags:
        - Password
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: VerificationCodeTooMany
                message: Too many attempts
          description: Too many attempts
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/accounts/password/recover:
    post:
      summary: Recovers password
      description: Recovers password for current user
      tags:
        - Password
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordRecoveryRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthAuthorized:
                  description: User is authorized
                  value:
                    errorCode: AuthAuthorized
                    message: User is authorized
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/accounts/password/recover/change:
    post:
      summary: Changes password for an UN-authorized user
      tags:
        - Password
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordRecoveryChange'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthAuthorized:
                  description: User is authorized
                  value:
                    errorCode: AuthAuthorized
                    message: User is authorized
                ConfirmationRequired:
                  description: Confirmation required
                  value:
                    errorCode: ConfirmationRequired
                    message: Confirmation required
                PasswordNotUpdated:
                  description: Failed to change password
                  value:
                    errorCode: PasswordNotUpdated
                    message: Failed to change password
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/accounts/password/recover/check-code:
    post:
      summary: Validates confirmation code for password change
      tags:
        - Password
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordRecoveryCode'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthAuthorized:
                  description: User is authorized
                  value:
                    errorCode: AuthAuthorized
                    message: User is authorized
                VerificationCodeError:
                  description: Incorrect verification code
                  value:
                    errorCode: VerificationCodeError
                    message: Incorrect verification code
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/accounts/phone/change/confirm/auth:
    post:
      summary: Confirm authentication with phone number
      description: >-
        Step 2. Validate the provided authentication code. After 3 failed
        attempts, the current user session will be invalidated.
      tags:
        - phone
      requestBody:
        content:
          text/plain:
            schema:
              format: int32
              type: integer
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                VerificationCodeError:
                  description: Incorrect verification code
                  value:
                    errorCode: VerificationCodeError
                    message: Incorrect verification code
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
                PhoneNotSet:
                  description: Phone number not set for this account
                  value:
                    errorCode: PhoneNotSet
                    message: Phone number not set for this account
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/accounts/phone/change/confirm/new-phone:
    post:
      summary: Change phone number for authenticated user
      description: >-
        Step 4. Validate the new verification code. Upon successful
        verification, the user's phone number will be updated to the newly
        verified number.
      tags:
        - phone
      requestBody:
        content:
          text/plain:
            schema:
              format: int32
              type: integer
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                VerificationCodeError:
                  description: Incorrect verification code
                  value:
                    errorCode: VerificationCodeError
                    message: Incorrect verification code
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
                PhoneNotSet:
                  description: Phone number not set for this account
                  value:
                    errorCode: PhoneNotSet
                    message: Phone number not set for this account
                PhoneNotUpdated:
                  description: Failed to update the phone number
                  value:
                    errorCode: PhoneNotUpdated
                    message: Failed to update the phone number
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PhoneExists
                message: This phone number is already associated with an account
          description: This phone number is already associated with an account
      security:
        - header: []
  /api/v1/accounts/phone/change/new-phone:
    post:
      summary: Request a new phone number
      description: >-
        Step 3. Request a new phone number from the user. Verification code will
        be sent via SMS to that number.
      tags:
        - phone
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddPhoneRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                VerificationCodeError:
                  description: Incorrect verification code
                  value:
                    errorCode: VerificationCodeError
                    message: Incorrect verification code
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
                PhoneNotSet:
                  description: Phone number not set for this account
                  value:
                    errorCode: PhoneNotSet
                    message: Phone number not set for this account
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/accounts/phone/change/request:
    put:
      summary: Request phone number change for authenticated user
      description: >-
        Step 1. Request an authentication code to be sent via SMS to the user's
        original phone number.
      tags:
        - phone
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
                PhoneNotSet:
                  description: Phone number not set for this account
                  value:
                    errorCode: PhoneNotSet
                    message: Phone number not set for this account
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/accounts/phone/change/resend-code/auth:
    put:
      summary: Resend code to check authentication with phone number
      tags:
        - phone
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
                PhoneNotSet:
                  description: Phone number not set for this account
                  value:
                    errorCode: PhoneNotSet
                    message: Phone number not set for this account
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/accounts/phone/change/resend-code/new-phone:
    put:
      summary: Resend code to confirm new phone number
      tags:
        - phone
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
                PhoneNotSet:
                  description: Phone number not set for this account
                  value:
                    errorCode: PhoneNotSet
                    message: Phone number not set for this account
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/accounts/profile:
    get:
      summary: Get current account profile
      description: >-
        Returns the authenticated account with all associated users. Most
        accounts have a single user, but the system supports multiple users per
        account. Requires authentication token.
      tags:
        - Accounts
      responses:
        '200':
          description: Account and users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountWithUser'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
      parameters:
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
  /api/v1/accounts/resend-code/{hash}:
    put:
      summary: Resend verification code
      description: >-
        Resends verification code via email or SMS based on registration type.
        Automatically detects whether to send email or SMS from the signup
        request. Rate limited to prevent abuse. Use when code was not received
        or expired.
      tags:
        - Accounts
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                SendEmailError:
                  description: Failed to send email
                  value:
                    errorCode: SendEmailError
                    message: Failed to send email
                SendSMSError:
                  description: Failed to send sms
                  value:
                    errorCode: SendSMSError
                    message: Failed to send sms
                VerificationCodeTooMany:
                  description: Too many attempts
                  value:
                    errorCode: VerificationCodeTooMany
                    message: Too many attempts
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountCreationError
                message: Failed to create the account
          description: Failed to create the account
      security: []
  /api/v1/accounts/resend-email/{hash}:
    put:
      summary: Resend confirmation email
      description: >-
        Resends the email verification code for pending registrations. Use when
        the initial email was not received or code expired. Rate limited to
        prevent abuse. Deprecated - use /resend-code instead.
      tags:
        - Accounts
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                EmailNotSet:
                  description: Email not set for this account
                  value:
                    errorCode: EmailNotSet
                    message: Email not set for this account
                SendEmailError:
                  description: Failed to send email
                  value:
                    errorCode: SendEmailError
                    message: Failed to send email
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/accounts/signup:
    post:
      summary: 'Signup - Step 1: Start email signup process'
      description: >-
        Initiates account registration with email verification. Step 1 of
        multi-step signup: validates input, checks availability, sends
        confirmation email. Returns registration hash for tracking signup
        progress. Username must not be reserved, email must be unique and not
        blocked.
      tags:
        - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreate'
        required: true
      responses:
        '200':
          description: >-
            Registration hash and next step. Hash can be used to resend
            confirmation email
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponse'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                RegistrationClosed:
                  description: Registration closed
                  value:
                    errorCode: RegistrationClosed
                    message: Registration closed
                SendEmailError:
                  description: Failed to send email
                  value:
                    errorCode: SendEmailError
                    message: Failed to send email
                InvitesNotEnabled:
                  description: Invite links are not enabled
                  value:
                    errorCode: InvitesNotEnabled
                    message: Invite links are not enabled
                InvalidInviteCode:
                  description: Invalid or exhausted invite code
                  value:
                    errorCode: InvalidInviteCode
                    message: Invalid or exhausted invite code
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EmailBlocked
                message: The email address or domain is blocked from registration
          description: The email address or domain is blocked from registration
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UserNameIsReserved:
                  description: The username is reserved and cannot be used
                  value:
                    errorCode: UserNameIsReserved
                    message: The username is reserved and cannot be used
                UserNameExists:
                  description: The username is already in use
                  value:
                    errorCode: UserNameExists
                    message: The username is already in use
                EmailExists:
                  description: The email address is already associated with an account
                  value:
                    errorCode: EmailExists
                    message: The email address is already associated with an account
          description: Conflict
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountCreationError
                message: Failed to create the account
          description: Failed to create the account
      security: []
  /api/v1/accounts/signup-phone:
    post:
      summary: 'Signup - Step 1: Start phone signup process'
      description: >-
        Initiates account registration with phone verification. Step 1 of
        multi-step signup: validates input, checks availability, sends SMS code.
        Returns registration hash for tracking signup progress. Username must
        not be reserved, phone number must be unique.
      tags:
        - Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneSignup'
        required: true
      responses:
        '200':
          description: >-
            Registration hash and next step. Hash can be used to resend
            confirmation code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponse'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                RegistrationClosed:
                  description: Registration closed
                  value:
                    errorCode: RegistrationClosed
                    message: Registration closed
                InvalidPhoneNumber:
                  description: The provided phone number is invalid
                  value:
                    errorCode: InvalidPhoneNumber
                    message: The provided phone number is invalid
                SendSMSError:
                  description: Failed to send sms
                  value:
                    errorCode: SendSMSError
                    message: Failed to send sms
                SMSServiceDisabled:
                  description: SMS service is not enabled
                  value:
                    errorCode: SMSServiceDisabled
                    message: SMS service is not enabled
                SMSUnsupportedCountry:
                  description: SMS service is not available in this country
                  value:
                    errorCode: SMSUnsupportedCountry
                    message: SMS service is not available in this country
                InvitesNotEnabled:
                  description: Invite links are not enabled
                  value:
                    errorCode: InvitesNotEnabled
                    message: Invite links are not enabled
                InvalidInviteCode:
                  description: Invalid or exhausted invite code
                  value:
                    errorCode: InvalidInviteCode
                    message: Invalid or exhausted invite code
          description: Bad Request
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UserNameIsReserved:
                  description: The username is reserved and cannot be used
                  value:
                    errorCode: UserNameIsReserved
                    message: The username is reserved and cannot be used
                UserNameExists:
                  description: The username is already in use
                  value:
                    errorCode: UserNameExists
                    message: The username is already in use
                PhoneExists:
                  description: This phone number is already associated with an account
                  value:
                    errorCode: PhoneExists
                    message: This phone number is already associated with an account
          description: Conflict
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountCreationError
                message: Failed to create the account
          description: Failed to create the account
      security: []
  /api/v1/accounts/user/reselect-user:
    post:
      summary: Switch between account users
      description: >-
        Generates a new token for a different user within the same account.
        Useful for accounts with multiple users to switch active user context.
        Either userId or userName must be provided. Only users belonging to the
        authenticated account can be selected.
      tags:
        - Accounts
      parameters:
        - description: User id
          required: false
          name: userId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Username
          required: false
          name: userName
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Session key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserIdOrUserNameMissing
                message: The userId or userName must be provided
          description: The userId or userName must be provided
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthUnauthorized:
                  description: A valid authentication token is required
                  value:
                    errorCode: AuthUnauthorized
                    message: A valid authentication token is required
                UserBadCreds:
                  description: Invalid user credentials provided
                  value:
                    errorCode: UserBadCreds
                    message: Invalid user credentials provided
          description: Unauthorized
      security:
        - header: []
  /api/v1/addresses/suggest:
    get:
      summary: Suggest addresses for the given address part
      tags:
        - Addresses
      parameters:
        - description: Address to complete
          required: true
          name: text
          in: query
          schema:
            type: string
      responses:
        '200':
          description: List of potential addresses matching the criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AddressData'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '429':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AddressesRequestRateExceeded
                message: The addresses API rate exceeded
          description: The addresses API rate exceeded
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AddressesError:
                  description: The addresses API error
                  value:
                    errorCode: AddressesError
                    message: The addresses API error
                AddressesAuthError:
                  description: The addresses API auth error
                  value:
                    errorCode: AddressesAuthError
                    message: The addresses API auth error
          description: Internal Server Error
      security:
        - header: []
  /api/v1/admin/account/{accountId}:
    get:
      summary: Retrieve account information by ID
      description: >-
        Fetches comprehensive details about an account including its associated
        users. Returns account metadata (email, creation date) and all users
        linked to this account. Most accounts have a single user, but the system
        supports multiple users per account.


        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: Account details with associated users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountWithUser'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/admin/audit_log:
    get:
      summary: List audit log entries
      description: >-
        Retrieves a paginated list of audit log entries with flexible filtering
        options. Returns security-relevant actions performed by users, accounts,
        or services within the platform.


        RBAC: requires Audit.Read
      tags:
        - Admin Audit
      parameters:
        - description: Filter by account ID (mutually exclusive with email parameter)
          example: ac_01hxcvk1hjexere4pvtrj0ymqq
          schema:
            type: string
            nullable: true
          name: accountId
          in: query
        - description: >-
            Filter by specific actions (e.g., CREATE, UPDATE, DELETE). Multiple
            values allowed.
          example:
            - CREATE
            - UPDATE
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AuditLogAction'
            nullable: true
          name: action
          in: query
        - description: Filter by application ID
          example: ap_01hxcvk1hjexere4pvtrj0ymqq
          schema:
            type: string
            nullable: true
          name: appId
          in: query
        - description: Search for entries related to specific domains
          example: example.com
          schema:
            type: string
            nullable: true
          name: domainSearch
          in: query
        - description: >-
            Filter by email address (mutually exclusive with accountId
            parameter)
          example: user@example.com
          schema:
            type: string
            nullable: true
          name: email
          in: query
        - description: >-
            Filter by audit log groups (e.g., ACCOUNT, USER, APP). Multiple
            values allowed.
          example:
            - ACCOUNT
            - USER
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AuditLogGroup'
            nullable: true
          name: group
          in: query
        - description: Filter by group ID
          example: gr_01hxcvk1hjexere4pvtrj0ymqq
          schema:
            type: string
            nullable: true
          name: groupId
          in: query
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Filter by rule ID
          example: ru_01hxcvk1hjexere4pvtrj0ymqq
          schema:
            type: string
            nullable: true
          name: ruleId
          in: query
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Filter by user ID (mutually exclusive with username parameter)
          example: us_01hxcvk1hjexere4pvtrj0ymqq
          schema:
            type: string
            nullable: true
          name: userId
          in: query
        - description: >-
            Filter by username with optional domain (e.g., 'john' or
            '@john@example.com'). Mutually exclusive with userId parameter.
          example: '@john@example.com'
          schema:
            type: string
            nullable: true
          name: username
          in: query
      responses:
        '200':
          description: Successfully retrieved audit log entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogResult'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ConstraintViolation
                message: A request parameter constraint was violated
          description: A request parameter constraint was violated
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/change/email:
    put:
      summary: Change email address for an account
      description: >-
        Administratively updates the email address for a user account. Can
        identify the user by username or user ID. The new email must be valid
        and unique in the system. This operation is logged for audit purposes
        and the change takes effect immediately.


        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      parameters:
        - description: >-
            New email address for the account. Must be a valid email format and
            unique in the system.
          required: true
          name: email
          in: query
          schema:
            type: string
        - description: >-
            User ID whose email to change. Must be a valid USER type ID. Either
            username or id must be provided.
          required: false
          name: id
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: >-
            Username of the user whose email to change. Case-insensitive. Either
            username or id must be provided.
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Email address successfully changed
          content:
            text/plain: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AdminNeedUsernameOrId
                message: Either a username or user ID must be provided
          description: Either a username or user ID must be provided
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/admin/change/password:
    put:
      summary: Change password for an account
      description: >-
        Administratively resets the password for a user account. Can identify
        the user by username or user ID. The new password should meet security
        requirements. This operation is logged for audit purposes and does not
        require knowing the current password.


        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      parameters:
        - description: >-
            User ID whose password to change. Must be a valid USER type ID.
            Either username or id must be provided.
          required: false
          name: id
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: New password for the account. Should meet security requirements.
          required: true
          name: password
          in: query
          schema:
            type: string
        - description: >-
            Username of the user whose password to change. Case-insensitive.
            Either username or id must be provided.
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Password successfully changed
          content:
            text/plain: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AdminNeedUsernameOrId
                message: Either a username or user ID must be provided
          description: Either a username or user ID must be provided
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/admin/change/role/assign:
    put:
      summary: Assign role to a user
      description: |-
        Assigns a role to a user by username or id

        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      parameters:
        - description: >-
            User ID to assign the role to. Must be a valid USER type ID. Either
            username or id must be provided.
          required: false
          name: id
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: >-
            Role ID to assign in format 'Scope:RoleName' (e.g., 'System:ADMIN',
            'Group:MODERATOR'). Must be a valid role.
          required: true
          name: role
          in: query
          schema:
            $ref: '#/components/schemas/RoleId'
        - description: >-
            Username of the user to assign the role to. Case-insensitive. Either
            username or id must be provided.
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountWithUser'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AdminNeedUsernameOrId
                message: Either a username or user ID must be provided
          description: Either a username or user ID must be provided
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                CantRemoveLastAdmin:
                  description: Cannot remove the last remaining admin user
                  value:
                    errorCode: CantRemoveLastAdmin
                    message: Cannot remove the last remaining admin user
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/admin/change/role/revoke:
    put:
      summary: Revoke role from a user
      description: >-
        Revokes a role from a user by username or id. Admin cannot be revoked if
        it's the last one.


        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      parameters:
        - description: >-
            User ID to revoke the role from. Must be a valid USER type ID.
            Either username or id must be provided.
          required: false
          name: id
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: >-
            Role ID to revoke in format 'Scope:RoleName'. Must currently be
            assigned to the user.
          required: true
          name: role
          in: query
          schema:
            $ref: '#/components/schemas/RoleId'
        - description: >-
            Username of the user to revoke the role from. Case-insensitive.
            Either username or id must be provided.
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountWithUser'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AdminNeedUsernameOrId
                message: Either a username or user ID must be provided
          description: Either a username or user ID must be provided
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                CantRemoveLastAdmin:
                  description: Cannot remove the last remaining admin user
                  value:
                    errorCode: CantRemoveLastAdmin
                    message: Cannot remove the last remaining admin user
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/admin/clear-ap-errors:
    post:
      summary: Clears ActivityPub delivery errors for the domain
      tags:
        - Admin ActivityPub
      parameters:
        - name: domain
          in: query
          schema:
            pattern: \S
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
      description: 'RBAC: requires Federation.Manage'
  /api/v1/admin/create-account:
    post:
      summary: Create a new account with initial user
      description: >-
        Creates a new account with an initial user profile. The account will
        have a unique email and the user will have a unique username. This
        endpoint validates that the username is not reserved, the username
        doesn't already exist, and the email is not already registered. Returns
        the created account with its associated user information.


        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreate'
        required: true
      responses:
        '200':
          description: Account successfully created with initial user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountWithUser'
        '400':
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UserNameIsReserved:
                  description: The username is reserved and cannot be used
                  value:
                    errorCode: UserNameIsReserved
                    message: The username is reserved and cannot be used
                UserNameExists:
                  description: The username is already in use
                  value:
                    errorCode: UserNameExists
                    message: The username is already in use
                EmailExists:
                  description: The email address is already associated with an account
                  value:
                    errorCode: EmailExists
                    message: The email address is already associated with an account
          description: Conflict
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountCreationError
                message: Failed to create the account
          description: Failed to create the account
      security: []
      parameters:
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
  /api/v1/admin/create-user:
    post:
      summary: Create a new user under an existing account
      description: >-
        Creates a new user profile under an existing account. The user will have
        a unique username within the account's domain. This endpoint validates
        that the username is not reserved, the username doesn't already exist,
        and the associated account exists. Returns the created user information.


        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      parameters:
        - description: Account id to add user to
          required: false
          name: account_id
          in: query
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      requestBody:
        description: JSON object with the user's data
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '200':
          description: User successfully created under existing account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFull'
        '400':
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UserNameIsReserved:
                  description: The username is reserved and cannot be used
                  value:
                    errorCode: UserNameIsReserved
                    message: The username is reserved and cannot be used
                UserNameExists:
                  description: The username is already in use
                  value:
                    errorCode: UserNameExists
                    message: The username is already in use
          description: Conflict
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserCreationError
                message: Failed to create the user
          description: Failed to create the user
      security: []
  /api/v1/admin/delete:
    delete:
      summary: Delete an account with all associated users
      description: >-
        Permanently deletes an account and all its associated users. Can
        identify the account by email address, account ID, or username. This
        operation notifies followers on remote servers about the deletion and
        marks all associated content appropriately. This action is irreversible.
        Administrators cannot delete their own account through this endpoint.


        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      parameters:
        - description: Email of the account to delete
          required: false
          name: email
          in: query
          schema:
            type: string
            nullable: true
        - description: Id of the account to delete
          required: false
          name: id
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Username of the account to delete
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Account and all associated users successfully deleted
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AdminNeedEmailAccIdUsername:
                  description: >-
                    Either an email address, account ID, or username must be
                    provided
                  value:
                    errorCode: AdminNeedEmailAccIdUsername
                    message: >-
                      Either an email address, account ID, or username must be
                      provided
                AdminDeleteAccWithSelf:
                  description: Cannot delete self
                  value:
                    errorCode: AdminDeleteAccWithSelf
                    message: Cannot delete self
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountIsNotRemoved
                message: Failed to remove the account
          description: Failed to remove the account
      security: []
  /api/v1/admin/delete-user:
    delete:
      summary: Delete a user
      description: >-
        Permanently deletes a user profile. Can identify the user by username or
        user ID. This operation notifies followers on remote servers about the
        deletion and marks all associated content appropriately. This action is
        irreversible. Administrators cannot delete their own user profile
        through this endpoint.


        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      parameters:
        - description: User ID to delete. Must be a valid USER type ID.
          required: false
          name: id
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Username of the user to delete. Case-insensitive.
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: User successfully deleted
          content:
            text/plain: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AdminNeedUsernameOrId:
                  description: Either a username or user ID must be provided
                  value:
                    errorCode: AdminNeedUsernameOrId
                    message: Either a username or user ID must be provided
                AdminDeleteAccWithSelf:
                  description: Cannot delete self
                  value:
                    errorCode: AdminDeleteAccWithSelf
                    message: Cannot delete self
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security: []
  /api/v1/admin/domain-allow:
    get:
      summary: List allowed domains
      description: >-
        Retrieves a paginated list of all domains in the federation allowlist.
        This list determines which external instances can federate with this
        server when allowlisting is enabled.


        RBAC:

        - requires ANY of Federation.Read, Federation.Manage
      tags:
        - Admin Domains Allow List
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: Successfully retrieved list of allowed domains
          content:
            application/json:
              examples:
                Domain list:
                  value:
                    - domain: mastodon.social
                      createdAt: '2024-01-15T10:30:00Z'
                    - domain: example.com
                      createdAt: '2024-01-16T14:20:00Z'
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AllowedDomain'
      security: []
    post:
      summary: Add domain to allowlist
      description: >-
        Adds a domain to the federation allowlist. When domain allowlisting is
        enabled, only domains in this list can federate with the instance.
        Cannot add the instance's own domain.


        RBAC: requires Federation.Manage
      tags:
        - Admin Domains Allow List
      requestBody:
        description: Domain to add to the allowlist
        content:
          application/json:
            examples:
              Add domain:
                value:
                  domain: example.com
            schema:
              $ref: '#/components/schemas/AllowedDomainReq'
        required: true
      responses:
        '200':
          description: Domain successfully added to allowlist
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: DomainAlreadyAllowed
                message: The domain is already allowed
          description: The domain is already allowed
      security: []
  /api/v1/admin/domain-allow/{domain}:
    delete:
      summary: Remove domain from allowlist
      description: >-
        Removes a domain from the federation allowlist. This will trigger
        background jobs to unfederate with the domain and clean up any existing
        connections.


        RBAC: requires Federation.Manage
      tags:
        - Admin Domains Allow List
      parameters:
        - description: Domain name to remove from the allowlist
          example: example.com
          required: true
          name: domain
          in: path
          schema:
            pattern: \S
            type: string
      responses:
        '200':
          description: Domain successfully removed from allowlist
          content:
            application/json:
              schema: {}
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                DomainIsNotAllowed:
                  description: The domain is not allowed
                  value:
                    errorCode: DomainIsNotAllowed
                    message: The domain is not allowed
          description: Forbidden
      security:
        - header: []
  /api/v1/admin/domain-block:
    put:
      summary: Update domain block
      description: >-
        Modifies an existing domain block with new settings. Can change the
        block severity, media/report rejection settings, comments, and
        obfuscation. Triggers background jobs if the state changes.


        RBAC: requires Federation.Manage
      tags:
        - Admin Domain Blocks
      requestBody:
        description: Updated domain block configuration
        content:
          application/json:
            examples:
              Upgrade to SUSPEND:
                value:
                  domain: spam.example
                  publicComment: Severe violations
                  state: SUSPEND
            schema:
              $ref: '#/components/schemas/BlockDomainReq'
        required: true
      responses:
        '200':
          description: Domain block successfully updated
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: DomainIsNotBlocked
                message: The domain is not currently blocked
          description: The domain is not currently blocked
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: DomainAlreadyBlocked
                message: The domain is already blocked
          description: The domain is already blocked
      security: []
    get:
      summary: List blocked domains (Admin)
      description: >-
        Retrieves the complete list of domains that are blocked, including all
        metadata such as private comments, exact domain names, and internal
        settings. This endpoint is for administrators only.


        RBAC:

        - requires ANY of Federation.Read, Federation.Manage
      tags:
        - Admin Domain Blocks
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: Successfully retrieved list of blocked domains
          content:
            application/json:
              examples:
                Blocked domains list:
                  value:
                    - domain: spam.example
                      publicComment: Spam
                      state: SUSPEND
                      rejectMedia: true
                      rejectReports: true
                      privateComment: Severe spam issues
                      obfuscate: false
                      createdAt: '2024-01-15T10:30:00Z'
                      updatedAt: '2024-01-15T10:30:00Z'
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BlockedDomain'
      security: []
    post:
      summary: Block a domain
      description: >-
        Creates a new domain block that prevents or limits interactions with the
        specified domain. The block severity can be SUSPEND (removes all
        content), LIMIT (hides posts from non-followers), or NOOP (only rejects
        media/reports). Cannot block the instance's own domain.


        RBAC: requires Federation.Manage
      tags:
        - Admin Domain Blocks
      requestBody:
        description: Domain block configuration
        content:
          application/json:
            examples:
              Block with LIMIT:
                value:
                  domain: spam.example
                  publicComment: Spam content
                  state: LIMIT
                  rejectMedia: true
            schema:
              $ref: '#/components/schemas/BlockDomainReq'
        required: true
      responses:
        '200':
          description: Domain successfully blocked
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: DomainAlreadyBlocked
                message: The domain is already blocked
          description: The domain is already blocked
      security: []
  /api/v1/admin/domain-block/{domain}:
    delete:
      summary: Unblock a domain
      description: >-
        Removes a block from a domain to allow interactions with it again. This
        triggers background jobs to restore any suspended accounts and content
        from the domain.


        RBAC: requires Federation.Manage
      tags:
        - Admin Domain Blocks
      parameters:
        - description: Domain name to unblock
          example: spam.example
          required: true
          name: domain
          in: path
          schema:
            pattern: \S
            type: string
      responses:
        '200':
          description: Domain successfully unblocked
          content:
            application/json:
              schema: {}
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: DomainIsNotBlocked
                message: The domain is not currently blocked
          description: The domain is not currently blocked
      security:
        - header: []
  /api/v1/admin/email-allow:
    get:
      summary: List email allowed domains
      description: |-
        Retrieves a paginated list of all domains in the email allowlist.

        RBAC:
        - requires ALL of AdminSettings.Manage
        - requires ANY of AdminSettings.Read, AdminSettings.Manage
      tags:
        - Admin Email Allow List
      responses:
        '200':
          description: Successfully retrieved list of allowed domains
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AllowedDomain'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: RBACInsufficientPermissions
                message: Insufficient permissions to perform this operation
          description: Insufficient permissions to perform this operation
      security: []
    post:
      summary: Add domain to email signup allowlist
      description: >-
        Adds a domain to the email allowlist. Only emails from allowed domains
        can register when enabled.


        RBAC: requires AdminSettings.Manage
      tags:
        - Admin Email Allow List
      requestBody:
        description: Domain to add to the email allowlist
        content:
          application/json:
            examples:
              Add domain:
                value:
                  domain: example.com
            schema:
              $ref: '#/components/schemas/AllowedDomainReq'
        required: true
      responses:
        '200':
          description: Domain successfully added to email allowlist
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                RBACInsufficientPermissions:
                  description: Insufficient permissions to perform this operation
                  value:
                    errorCode: RBACInsufficientPermissions
                    message: Insufficient permissions to perform this operation
                EmailBlocked:
                  description: The email address or domain is blocked from registration
                  value:
                    errorCode: EmailBlocked
                    message: The email address or domain is blocked from registration
          description: Forbidden
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EmailAlreadyAllowed
                message: Email domain is already allowed for registration
          description: Email domain is already allowed for registration
      security: []
  /api/v1/admin/email-allow/{domain}:
    delete:
      summary: Remove domain from email signup allowlist
      description: |-
        Removes a domain from the email allowlist.

        RBAC: requires AdminSettings.Manage
      tags:
        - Admin Email Allow List
      parameters:
        - description: Domain name to remove from the allowlist
          example: example.com
          required: true
          name: domain
          in: path
          schema:
            pattern: \S
            type: string
      responses:
        '200':
          description: Domain successfully removed from email allowlist
          content:
            application/json:
              schema: {}
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: RBACInsufficientPermissions
                message: Insufficient permissions to perform this operation
          description: Insufficient permissions to perform this operation
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EmailAllowNotFound
                message: Email domain allow entry not found
          description: Email domain allow entry not found
      security: []
  /api/v1/admin/email-block:
    get:
      summary: List blocked email patterns
      description: >-
        Retrieves the complete list of email patterns and domains that are
        blocked for signups. Includes the blocking reason and timestamps for
        each pattern. Patterns are shown in their normalized form.


        RBAC: requires Users.Moderate
      tags:
        - Admin Email Blocks
      responses:
        '200':
          description: Successfully retrieved list of blocked email patterns
          content:
            application/json:
              examples:
                Email blocks list:
                  value:
                    - pattern: spammer@example.com
                      reason: Known spam account
                      createdAt: '2024-01-15T10:30:00Z'
                    - pattern: spam-domain.com
                      reason: Spam domain
                      createdAt: '2024-01-16T14:20:00Z'
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmailBlock'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: RBACInsufficientPermissions
                message: Insufficient permissions to perform this operation
          description: Insufficient permissions to perform this operation
      security: []
    post:
      summary: Block email pattern
      description: >-
        Creates a new email block that prevents signups from the specified email
        pattern. Supports blocking: specific emails (user@example.com) or domain
        patterns (example.com). Patterns are automatically normalized for
        consistency.


        RBAC: requires Users.Moderate
      tags:
        - Admin Email Blocks
      requestBody:
        description: Email pattern and reason for blocking
        content:
          application/json:
            examples:
              Block specific email:
                value:
                  pattern: spammer@example.com
                  reason: Known spam account
              Block domain:
                value:
                  pattern: spam-domain.com
                  reason: Spam domain
            schema:
              $ref: '#/components/schemas/BlockEmailRequest'
        required: true
      responses:
        '200':
          description: Email pattern successfully blocked
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: RBACInsufficientPermissions
                message: Insufficient permissions to perform this operation
          description: Insufficient permissions to perform this operation
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EmailAlreadyBlocked
                message: The email pattern is already blocked
          description: The email pattern is already blocked
      security: []
  /api/v1/admin/email-block/{pattern}:
    delete:
      summary: Unblock email pattern
      description: >-
        Removes a block from an email pattern or domain to allow signups from it
        again. The pattern will be normalized before removal to match the stored
        format.


        RBAC: requires Users.Moderate
      tags:
        - Admin Email Blocks
      parameters:
        - description: Email pattern to unblock (will be normalized)
          examples:
            Specific email:
              value: user@example.com
            Block domain:
              value: example.com
          required: true
          name: pattern
          in: path
          schema:
            pattern: \S
            type: string
      responses:
        '200':
          description: Email pattern successfully unblocked
          content:
            application/json:
              schema: {}
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: RBACInsufficientPermissions
                message: Insufficient permissions to perform this operation
          description: Insufficient permissions to perform this operation
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EmailNotBlocked
                message: The email pattern is not blocked
          description: The email pattern is not blocked
      security: []
  /api/v1/admin/federation:
    get:
      summary: List federated domains
      description: >-
        Retrieves a paginated list of all domains this instance is federated
        with, including user counts, availability status, and blocking state.
        Supports filtering by domain name, availability, and block status.
      tags:
        - Admin Federation Metrics
      parameters:
        - description: >-
            Filter by blocking state(s) - accepts single state or
            comma-separated list (LIMITED, SUSPENDED, NOOP)
          required: false
          name: blockState
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/DomainBlockState'
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Filter domains by name
          required: false
          name: search
          in: query
          schema:
            type: string
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: Filter only unavailable domains (7+ days not responding)
          required: false
          name: unavailable
          in: query
          schema:
            type: boolean
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Filter only failing domains (1+ days not responding)
          required: false
          name: warning
          in: query
          schema:
            type: boolean
            nullable: true
      responses:
        '200':
          description: Successfully retrieved list of federated domains
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServersResult'
      security: []
  /api/v1/admin/federation/metrics/operations:
    get:
      summary: List tracked ActivityPub operations
      description: >-
        Retrieves a list of all ActivityPub operations that have been tracked on
        this server. An operation combines the Activity type with the inner
        object type (if present). Examples: 'create-note' (Create activity with
        Note object), 'follow' (Follow activity), 'accept-follow' (Accept
        activity with Follow object), 'announce' (boost/reblog),
        'undo-announce'.


        RBAC:

        - requires ANY of Federation.Read, Federation.Manage
      tags:
        - Admin Federation Metrics
      parameters:
        - description: Time window to check for operations (defaults to 24h)
          example: ONE_HOUR
          required: false
          name: window
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/WindowSize'
            nullable: true
      responses:
        '200':
          description: Successfully retrieved list of tracked operations
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                  - follow
                  - accept-follow
                  - create-note
                  - announce
                  - undo-follow
                  - like
                  - undo-like
      security: []
  /api/v1/admin/federation/metrics/running-average-single:
    get:
      summary: Get metrics for specific operation
      description: >-
        Returns sliding window metrics for a single ActivityPub operation,
        including count, average processing time, and percentiles. The metrics
        are calculated over the specified time window. Returns 404 if no data
        exists for the operation or the window has expired.


        RBAC:

        - requires ANY of Federation.Read, Federation.Manage
      tags:
        - Admin Federation Metrics
      parameters:
        - description: The ActivityPub operation to get metrics for
          example: follow
          required: true
          name: operation
          in: query
          schema:
            type: string
        - description: >-
            Time window for metric calculation (e.g., ONE_HOUR, SIX_HOURS,
            TWENTY_FOUR_HOURS)
          example: ONE_HOUR
          required: true
          name: window
          in: query
          schema:
            $ref: '#/components/schemas/WindowSize'
      responses:
        '200':
          description: Successfully retrieved operation metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlidingWindowMetrics'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security: []
  /api/v1/admin/federation/metrics/running-averages-all:
    get:
      summary: Get metrics for multiple operations
      description: >-
        Returns sliding window metrics for all ActivityPub operations or a
        filtered subset. Only includes operations that have active data within
        the specified time window. Each operation's metrics include count,
        average processing time, and percentiles.


        RBAC:

        - requires ANY of Federation.Read, Federation.Manage
      tags:
        - Admin Federation Metrics
      parameters:
        - description: >-
            Comma-separated list of specific operations to get metrics for. If
            omitted, returns all operations.
          example: follow,create-note,announce
          required: false
          name: operations
          in: query
          schema:
            type: array
            items:
              type: string
            nullable: true
        - description: Time window for metric calculation
          example: TWENTY_FOUR_HOURS
          required: true
          name: window
          in: query
          schema:
            $ref: '#/components/schemas/WindowSize'
      responses:
        '200':
          description: Map of operation names to their corresponding metrics
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/SlidingWindowMetrics'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/federation/{domain}:
    get:
      summary: Get domain federation details
      description: >-
        Retrieves detailed federation statistics for a specific domain,
        including user counts, post counts, follower/following relationships,
        reports, availability status, and blocking information.


        RBAC:

        - requires ANY of Federation.Read, Federation.Manage
      tags:
        - Admin Federation Metrics
      parameters:
        - description: Domain name to get federation details for
          example: mastodon.social
          required: true
          name: domain
          in: path
          schema:
            pattern: \S
            type: string
      responses:
        '200':
          description: Successfully retrieved domain federation information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerInfo'
      security: []
  /api/v1/admin/feed/clear-user-feed:
    post:
      summary: Clear user feed cache
      description: >-
        Removes cached feed data from Redis for specified user(s). If no user is
        specified, clears all cached feeds. Use with caution as this will force
        feed regeneration on next access. Returns the number of Redis keys
        deleted.


        RBAC: requires Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: 'Specific owner type to clear cache for (default: all types)'
          example: GROUP
          required: false
          name: ownerType
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/PostOwnerType'
            nullable: true
        - description: 'User ID to clear feed cache for (default: all users)'
          example: us_01234567890abcdef
          required: false
          name: userId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Username to clear feed cache for (alternative to userId)
          example: jane_doe
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Number of Redis cache keys deleted
          content:
            application/json:
              schema: {}
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/diagnose:
    get:
      summary: Diagnose user feed cache
      tags:
        - Admin Feeds
      parameters:
        - description: compare N posts from home feed to DB feed
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: 'Specific owner type to diagnose (default: all types)'
          example: GROUP
          required: true
          name: ownerType
          in: query
          schema:
            $ref: '#/components/schemas/PostOwnerType'
        - description: Skip exact match
          required: false
          name: skipExactMatch
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Don't show full feed
          required: false
          name: skipFull
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Skip order match
          required: false
          name: skipOrderMismatch
          in: query
          schema:
            type: boolean
            nullable: true
        - example: us_01234567890abcdef
          required: false
          name: userId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - example: jane_doe
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Map of userIds to their diagnosed results
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/FeedCompareResult'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
      description: 'RBAC: requires Jobs.Manage'
  /api/v1/admin/feed/metrics/global-all-operation:
    get:
      summary: Get metrics across all operations
      description: >-
        Retrieves global aggregated metrics for a specific owner type across all
        feed operations within a time window.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: Owner type to filter metrics
          example: GROUP
          required: true
          name: ownerType
          in: query
          schema:
            $ref: '#/components/schemas/PostOwnerType'
        - description: Time window for aggregation
          example: 24h
          required: true
          name: window
          in: query
          schema:
            $ref: '#/components/schemas/WindowSize'
      responses:
        '200':
          description: List of global aggregated metrics for all operations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GlobalAggregatedMetrics'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/metrics/global-all-owners:
    get:
      summary: Get metrics across all owner types
      description: >-
        Retrieves global aggregated metrics for a specific operation across all
        owner types (USER, GROUP, EVENT, CATEGORY) within a time window.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: Feed operation type to analyze
          example: merge
          required: true
          name: operation
          in: query
          schema:
            $ref: '#/components/schemas/FeedOperation'
        - description: Time window for aggregation
          example: 1h
          required: true
          name: window
          in: query
          schema:
            $ref: '#/components/schemas/WindowSize'
      responses:
        '200':
          description: List of global aggregated metrics for all owner types
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GlobalAggregatedMetrics'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/metrics/global-single:
    get:
      summary: Get global aggregated metrics
      description: >-
        Retrieves global aggregated feed performance metrics for a specific
        operation and owner type combination within a time window. Includes
        average times, total measurements, and user counts.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: >-
            Feed operation type (populate, merge, unmerge, redis, redisLex,
            cache, idsDb, db, add, remove)
          example: populate
          required: true
          name: operation
          in: query
          schema:
            $ref: '#/components/schemas/FeedOperation'
        - description: Owner type (USER, GROUP, EVENT, CATEGORY)
          example: USER
          required: true
          name: ownerType
          in: query
          schema:
            $ref: '#/components/schemas/PostOwnerType'
        - description: >-
            Time window for aggregation (TEN_MINUTES, ONE_HOUR,
            TWENTY_FOUR_HOURS or 10m, 1h, 24h)
          example: ONE_HOUR
          required: true
          name: window
          in: query
          schema:
            $ref: '#/components/schemas/WindowSize'
      responses:
        '200':
          description: Global aggregated metrics for the specified operation and owner type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalAggregatedMetrics'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/metrics/history:
    get:
      summary: Get feed metrics history
      description: >-
        Retrieves historical feed performance metrics for a specific operation,
        user, and owner type combination. Returns a list of feed metrics ordered
        by timestamp.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: 'Maximum number of historical entries to return (default: 100)'
          example: 100
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
        - description: >-
            Feed operation type to filter metrics (e.g., populate, merge, redis,
            cache)
          example: populate
          required: true
          name: operation
          in: query
          schema:
            $ref: '#/components/schemas/FeedOperation'
        - description: Owner type to filter metrics (USER, GROUP, EVENT, or CATEGORY)
          example: USER
          required: true
          name: ownerType
          in: query
          schema:
            $ref: '#/components/schemas/PostOwnerType'
        - description: User ID to retrieve metrics for
          example: us_01234567890abcdef
          required: true
          name: userId
          in: query
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Feed metrics history retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FeedMetrics'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/metrics/history/all:
    get:
      summary: Get comprehensive feed metrics
      description: >-
        Retrieves complete feed metrics history for a user across all operations
        and all owner types. Returns a nested map structure where the outer keys
        are owner types, inner keys are operation types, and values are lists of
        feed metrics.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: >-
            Maximum number of historical entries per operation per owner type
            (default: 100)
          example: 100
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
        - description: User ID to retrieve comprehensive metrics for
          example: us_01234567890abcdef
          required: true
          name: userId
          in: query
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Nested map of owner types to operation types to feed metrics lists
          content:
            application/json:
              schema:
                type: object
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/metrics/history/all-single-owner:
    get:
      summary: Get feed metrics for all operations
      description: >-
        Retrieves comprehensive feed metrics history for a user across all
        operation types (populate, merge, unmerge, redis, cache, etc.) for a
        specific owner type. Returns a map where keys are operation types and
        values are lists of metrics.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: 'Maximum number of historical entries per operation (default: 100)'
          example: 100
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
        - description: Owner type to filter metrics (USER, GROUP, EVENT, or CATEGORY)
          example: GROUP
          required: true
          name: ownerType
          in: query
          schema:
            $ref: '#/components/schemas/PostOwnerType'
        - description: User ID to retrieve metrics for
          example: us_01234567890abcdef
          required: true
          name: userId
          in: query
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Map of feed operations to their corresponding metrics lists
          content:
            application/json:
              schema:
                type: object
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/metrics/history/by-owner-type:
    get:
      summary: Get feed metrics grouped by owner type
      description: >-
        Retrieves feed metrics history for a specific operation and user,
        grouped by all owner types (USER, GROUP, EVENT, CATEGORY). Returns a map
        where keys are owner types and values are lists of feed metrics.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: 'Maximum number of historical entries per owner type (default: 100)'
          example: 100
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
        - description: Feed operation type to filter metrics
          example: merge
          required: true
          name: operation
          in: query
          schema:
            $ref: '#/components/schemas/FeedOperation'
        - description: User ID to retrieve metrics for
          example: us_01234567890abcdef
          required: true
          name: userId
          in: query
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Map of owner types to their corresponding feed metrics lists
          content:
            application/json:
              schema:
                type: object
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/metrics/running-average-single:
    get:
      summary: Get user running average
      description: >-
        Retrieves the running average performance metrics for a specific user,
        operation, and owner type within a sliding time window.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: Feed operation to analyze
          example: populate
          required: true
          name: operation
          in: query
          schema:
            $ref: '#/components/schemas/FeedOperation'
        - description: Owner type to filter metrics
          example: USER
          required: true
          name: ownerType
          in: query
          schema:
            $ref: '#/components/schemas/PostOwnerType'
        - description: User ID to analyze
          example: us_01234567890abcdef
          required: true
          name: userId
          in: query
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Sliding window size for averaging
          example: 1h
          required: true
          name: window
          in: query
          schema:
            $ref: '#/components/schemas/WindowSize'
      responses:
        '200':
          description: Running average metrics for the specified operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlidingWindowMetrics'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/metrics/running-averages-all:
    get:
      summary: Get all user running averages
      description: >-
        Retrieves running average performance metrics for a specific user across
        all feed operations for a given owner type.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: Owner type to filter metrics
          example: GROUP
          required: true
          name: ownerType
          in: query
          schema:
            $ref: '#/components/schemas/PostOwnerType'
        - description: User ID to analyze
          example: us_01234567890abcdef
          required: true
          name: userId
          in: query
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Sliding window size for averaging
          example: 10m
          required: true
          name: window
          in: query
          schema:
            $ref: '#/components/schemas/WindowSize'
      responses:
        '200':
          description: Map of operations to running average metrics
          content:
            application/json:
              schema:
                type: object
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/metrics/slowest-operations:
    get:
      summary: Identify slowest feed operations
      description: >-
        Analyzes and ranks feed operations by their average execution time
        across all users. Helps identify performance bottlenecks.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: 'Maximum number of operations to return (default: 10)'
          example: 10
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
        - description: Optional owner type filter
          example: USER
          required: false
          name: ownerType
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/PostOwnerType'
            nullable: true
        - description: Time window for analysis
          example: 1h
          required: true
          name: window
          in: query
          schema:
            $ref: '#/components/schemas/WindowSize'
      responses:
        '200':
          description: Slowest operations data with analysis results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlowestOperationsResponse'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/metrics/slowest-users:
    get:
      summary: Identify users with performance issues
      description: >-
        Analyzes and identifies users experiencing the slowest feed operation
        times. Can analyze a specific operation or aggregate across all
        operations.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: 'Maximum number of users to return (default: 10)'
          example: 10
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
        - description: Optional specific operation to analyze
          example: populate
          required: false
          name: operation
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/FeedOperation'
            nullable: true
        - description: Owner type to analyze
          example: USER
          required: true
          name: ownerType
          in: query
          schema:
            $ref: '#/components/schemas/PostOwnerType'
        - description: Time window for analysis
          example: 1h
          required: true
          name: window
          in: query
          schema:
            $ref: '#/components/schemas/WindowSize'
      responses:
        '200':
          description: Slowest users data with detailed performance analysis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlowestUsersResponse'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/metrics/slowest-users-all:
    get:
      summary: Get performance leaderboards for all operations
      description: >-
        Retrieves performance leaderboards for all feed operations for a
        specific owner type. Returns a map of operations to ranked user lists.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: 'Maximum number of users per operation (default: 10)'
          example: 10
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
        - description: Owner type to analyze
          example: EVENT
          required: true
          name: ownerType
          in: query
          schema:
            $ref: '#/components/schemas/PostOwnerType'
        - description: >-
            Sort in descending order - true for fastest users first, false for
            slowest users first (default: true)
          example: true
          required: false
          name: sortDesc
          in: query
          schema:
            type: boolean
        - description: Time window for performance analysis
          example: 24h
          required: true
          name: window
          in: query
          schema:
            $ref: '#/components/schemas/WindowSize'
      responses:
        '200':
          description: Map of operations to lists of users ranked by performance
          content:
            application/json:
              schema:
                type: object
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/metrics/slowest-users-single:
    get:
      summary: Get performance leaderboard
      description: >-
        Retrieves a ranked list of users by their feed operation performance for
        a specific operation and owner type. Can show either slowest or fastest
        users based on sort order.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: 'Maximum number of users to return (default: 10)'
          example: 10
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
        - description: Feed operation to analyze
          example: redis
          required: true
          name: operation
          in: query
          schema:
            $ref: '#/components/schemas/FeedOperation'
        - description: Owner type to analyze
          example: USER
          required: true
          name: ownerType
          in: query
          schema:
            $ref: '#/components/schemas/PostOwnerType'
        - description: >-
            Sort in descending order - true for fastest users first, false for
            slowest users first (default: true)
          example: true
          required: false
          name: sortDesc
          in: query
          schema:
            type: boolean
        - description: Time window for performance analysis
          example: 1h
          required: true
          name: window
          in: query
          schema:
            $ref: '#/components/schemas/WindowSize'
      responses:
        '200':
          description: List of users ranked by performance metrics
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserPerformanceMetrics'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/metrics/summary:
    get:
      summary: Get comprehensive metrics summary
      description: >-
        Generates a complete summary of feed performance metrics across all
        operations and owner types, including totals and averages.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: >-
            Include user counts in summary (may impact performance, default:
            false)
          example: false
          required: false
          name: includeUserCounts
          in: query
          schema:
            type: boolean
        - description: Time window for metrics aggregation
          example: 1h
          required: true
          name: window
          in: query
          schema:
            $ref: '#/components/schemas/WindowSize'
      responses:
        '200':
          description: Comprehensive metrics summary with operation metrics and totals
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsSummary'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/metrics/user-count-all:
    get:
      summary: Get comprehensive user counts
      description: >-
        Returns user counts for all feed operations and owner types within the
        time window. Returns a nested map structure for comprehensive analysis.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: Optional owner type filter to limit results
          example: GROUP
          required: false
          name: ownerType
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/PostOwnerType'
            nullable: true
        - description: Time window to count active users within
          example: 24h
          required: true
          name: window
          in: query
          schema:
            $ref: '#/components/schemas/WindowSize'
      responses:
        '200':
          description: Nested map of operations to owner types to user counts
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  format: int64
                  type: integer
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/metrics/user-count-single:
    get:
      summary: Get active user count
      description: >-
        Returns the count of unique users who performed a specific feed
        operation within the time window, optionally filtered by owner type.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: Feed operation to count users for
          example: populate
          required: true
          name: operation
          in: query
          schema:
            $ref: '#/components/schemas/FeedOperation'
        - description: Optional owner type filter
          example: USER
          required: false
          name: ownerType
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/PostOwnerType'
            nullable: true
        - description: Time window to count active users within
          example: 1h
          required: true
          name: window
          in: query
          schema:
            $ref: '#/components/schemas/WindowSize'
      responses:
        '200':
          description: User count data for the specified operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCountResponse'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/feed/regenerate-user-feed:
    post:
      summary: Regenerate user feed cache
      description: >-
        Forces regeneration of cached feed data for specified user(s). If no
        user is specified, regenerates feeds for all recently active users
        (signed in within the last period). Returns the number of feeds queued
        for regeneration.


        RBAC: requires Jobs.Manage
      tags:
        - Admin Feeds
      parameters:
        - description: Clear before
          required: false
          name: clear
          in: query
          schema:
            type: boolean
            nullable: true
        - description: 'Specific owner type to regenerate feed for (default: all types)'
          example: USER
          required: false
          name: ownerType
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/PostOwnerType'
            nullable: true
        - description: User ID to regenerate feed for
          example: us_01234567890abcdef
          required: false
          name: userId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Username to regenerate feed for (alternative to userId)
          example: john_doe
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Number of user feeds queued for regeneration
          content:
            application/json:
              schema: {}
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security: []
  /api/v1/admin/groups/search:
    get:
      summary: Search for groups
      description: >-
        Administrative search for groups with multiple filter criteria. Filters
        include member user/account linkage, group name, domain, privacy,
        visibility, and join mode. Returns groups regardless of
        visibility/privacy.


        RBAC:

        - requires ANY of Users.Read, Users.Manage
      tags:
        - Admin Groups
      parameters:
        - description: Account ID of any group member
          required: false
          name: accountId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Display name of the group
          required: false
          name: displayName
          in: query
          schema:
            type: string
            nullable: true
        - description: Group domain (remote groups)
          required: false
          name: domain
          in: query
          schema:
            type: string
            nullable: true
        - description: Member account email
          required: false
          name: email
          in: query
          schema:
            type: string
            nullable: true
        - description: Group join mode
          required: false
          name: joinMode
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/GroupJoinMode'
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Group privacy
          required: false
          name: privacy
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/GroupPrivacy'
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: User ID of any group member
          required: false
          name: userId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Group username (groupname)
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
        - description: Group visibility
          required: false
          name: visibility
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/GroupVisibility'
            nullable: true
      responses:
        '200':
          description: List of groups matching filters
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/groups/user/{userId}:
    get:
      summary: >-
        Get all groups where specified user has at least one of the specified
        roles
      tags:
        - Admin Groups
      parameters:
        - description: The user ID to query groups for
          required: true
          name: userId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: List of group roles to filter by
          required: true
          name: roles
          in: query
          schema:
            type: array
            items:
              type: string
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: Group member status filter. Defaults to MEMBER
          required: false
          name: status
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/GroupMemberStatus'
              - default: MEMBER
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of groups with user's role information
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserGroupSummary'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security: []
      description: |-
        RBAC:
        - requires ANY of Users.Read, Users.Manage
  /api/v1/admin/groups/{accountId}:
    get:
      summary: >-
        Get groups that were created by the specified account (any user from the
        account is the owner)
      tags:
        - Admin Groups
      parameters:
        - description: The account id
          required: true
          name: accountId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security: []
      description: |-
        RBAC:
        - requires ANY of Users.Read, Users.Manage
  /api/v1/admin/groups/{groupId}/categories:
    get:
      summary: Get group's forum categories (admin)
      tags:
        - Admin Groups
      parameters:
        - description: Group ID
          required: true
          name: groupId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of forum categories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Category'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupNotFound
                message: Group not found
          description: Group not found
      security: []
      description: |-
        RBAC:
        - requires ANY of Users.Read, Users.Manage
  /api/v1/admin/groups/{groupId}/channels:
    get:
      summary: Get all channels for a group (admin)
      tags:
        - Admin Groups
      parameters:
        - description: Group ID
          required: true
          name: groupId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: List of group channels
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
      description: |-
        RBAC:
        - requires ANY of Users.Read, Users.Manage
  /api/v1/admin/groups/{groupId}/events:
    get:
      summary: Get group events (admin)
      tags:
        - Admin Groups
      parameters:
        - description: Group ID
          required: true
          name: groupId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Include translation
          required: false
          name: withTranslation
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/Language'
            nullable: true
      responses:
        '200':
          description: List of group-owned events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
      description: |-
        RBAC:
        - requires ANY of Users.Read, Users.Manage
  /api/v1/admin/impersonate:
    get:
      summary: Impersonate a user
      description: >-
        Allows a service to impersonate a user by their username. This will
        return a token that can be used to act on behalf the user's account.
        Only bots can be impersonated, not regular users.


        RBAC:

        - requires ALL of Users.Manage, Users.Impersonate
      tags:
        - Admin Accounts
      parameters:
        - description: >-
            Username of the bot user to impersonate. Must be a bot account, not
            a regular user. Case-insensitive.
          required: true
          name: username
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Session key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserIsNotBot
                message: The user is not a bot
          description: The user is not a bot
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security: []
  /api/v1/admin/link-service:
    get:
      summary: Get current remote link preview service configuration
      description: >-
        Returns the configured remote link preview service base URL if set;
        otherwise null.


        RBAC: requires AdminSettings.Manage
      tags:
        - Admin Remote Link Service
      responses:
        '200':
          description: Current configuration returned
          content:
            application/json:
              schema: {}
      security: []
  /api/v1/admin/link-service/configure:
    post:
      summary: Configure remote link preview service
      description: >-
        Validates the provided base URL, checks provider capabilities at
        /provider_info, and saves configuration


        RBAC: requires AdminSettings.Manage
      tags:
        - Admin Remote Link Service
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigureRequest'
        required: true
      responses:
        '200':
          description: Configuration saved successfully
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ClientError
                message: Invalid request from client
          description: Invalid request from client
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/posts/delete:
    post:
      summary: Delete posts
      description: >-
        Deletes posts for moderation purposes. Can delete a single post by its
        ID or all posts associated with a report. The deletion is permanent and
        includes creating audit logs and report notes. When deleting via
        reportId, all posts referenced in the report are deleted and the report
        is marked as actioned.


        RBAC: requires Reports.Manage
      tags:
        - Admin Posts
      requestBody:
        description: >-
          Post deletion request. Must provide either postId (for single post) or
          reportId (for all posts in report). The reason is required and will be
          recorded in the audit log.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostDelete'
        required: true
      responses:
        '200':
          description: Post(s) successfully deleted and audit logged
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                PostNotFound:
                  description: The specified post not found
                  value:
                    errorCode: PostNotFound
                    message: The specified post not found
                ReportNotFound:
                  description: The specified report not found
                  value:
                    errorCode: ReportNotFound
                    message: The specified report not found
                ReportPostsNotFound:
                  description: No posts found in the specified report
                  value:
                    errorCode: ReportPostsNotFound
                    message: No posts found in the specified report
          description: Not Found
      security: []
  /api/v1/admin/purge:
    delete:
      summary: Permanently purge an account from the system
      description: >-
        Force-deletes an account and all associated data, even if previously
        soft-deleted. This operation bypasses normal deletion safeguards and
        completely removes all traces of the account from the system. Use with
        extreme caution as this action is irreversible and cannot be recovered.
        Administrators cannot purge their own account.


        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      parameters:
        - description: Id of the account to purge
          required: true
          name: id
          in: query
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Account successfully purged from the system
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AdminDeleteAccWithSelf
                message: Cannot delete self
          description: Cannot delete self
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountIsNotRemoved
                message: Failed to remove the account
          description: Failed to remove the account
      security: []
  /api/v1/admin/regenerate-keys:
    post:
      summary: Regenerate cryptographic keys for a user
      description: >-
        Regenerates the Ed25519 cryptographic keys for a specified user. This is
        used for federation security and ActivityPub signatures. Can identify
        the user by username or user ID. The old keys are invalidated and new
        keys are generated immediately. Remote servers will be notified of the
        key change through federation protocols.


        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      parameters:
        - description: >-
            User ID whose cryptographic keys to regenerate. Must be a valid USER
            type ID. Either username or userId must be provided.
          required: false
          name: userId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: >-
            Username of the user whose keys to regenerate. Case-insensitive.
            Either username or userId must be provided.
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Keys successfully regenerated
          content:
            text/plain: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AdminNeedUsernameOrId:
                  description: Either a username or user ID must be provided
                  value:
                    errorCode: AdminNeedUsernameOrId
                    message: Either a username or user ID must be provided
                ClientError:
                  description: Invalid request from client
                  value:
                    errorCode: ClientError
                    message: Invalid request from client
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/admin/regenerate-keys-all:
    post:
      summary: Regenerate cryptographic keys for all users
      description: >-
        Initiates a background job to regenerate Ed25519 cryptographic keys for
        all users in the system. This is typically used for security updates or
        key rotation policies. The operation runs asynchronously and processes
        users in batches. Returns a job ID that can be used to track progress.
        Default batch size is used unless specified.


        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      parameters:
        - name: batch
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
      responses:
        '200':
          description: Background job initiated, returns job UUID
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/UUID'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/release-username:
    post:
      summary: Release a username for reuse
      description: >-
        Administratively releases a username, making it available for new user
        registrations. This is typically used after account deletions or
        username changes to free up desirable usernames. The operation
        immediately makes the username available in the system.


        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      parameters:
        - description: username
          required: true
          name: username
          in: query
          schema:
            pattern: \S
            type: string
      responses:
        '200':
          description: Username successfully released
          content:
            text/plain: {}
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/reports/delete-posts:
    post:
      summary: Remove posts from all reports and auto-close empty reports
      description: >-
        Removes specified posts from all reports that reference them. If a
        report no longer has any posts after removal, it is automatically
        closed/resolved. This is typically used after deleting reported content.
        Returns the count of reports that were auto-closed. The current user is
        recorded as having taken action on auto-closed reports.


        RBAC: requires Reports.Manage
      tags:
        - Admin Reports
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/TypeId'
        required: true
      responses:
        '200':
          description: >-
            Operation successful, returns number of reports that were
            auto-closed
          content:
            text/plain:
              schema:
                format: int32
                type: integer
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/reports/list:
    get:
      summary: List moderation reports with filtering
      description: >-
        Retrieves a paginated list of moderation reports. Can filter by reported
        user, reported post, group context, or resolution status. Supports
        pagination for large result sets. Reports include details about the
        reporter, target content, assigned moderator, and any notes.


        RBAC: requires Reports.Manage
      tags:
        - Admin Reports
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: >-
            Filter by resolution status. true = open reports only, false =
            resolved reports only, omit = all reports
          required: false
          name: open
          in: query
          schema:
            type: boolean
            nullable: true
        - description: >-
            Filter by reported post ID. Returns reports containing this specific
            post.
          required: false
          name: postId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: >-
            Filter by reported user ID. Returns reports targeting this specific
            user.
          required: false
          name: userId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: Paginated list of reports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportsPaginatedResponse'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/reports/{reportId}:
    get:
      summary: Get specific report details
      description: >-
        Retrieves complete details of a specific moderation report including the
        reporter, target content (users/posts), assigned moderator, resolution
        status, and all associated notes. Use this to review a report before
        taking action.


        RBAC: requires Reports.Manage
      tags:
        - Admin Reports
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Report details successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ReportNotFound
                message: The specified report not found
          description: The specified report not found
      security: []
  /api/v1/admin/reports/{reportId}/add-note:
    post:
      summary: Add moderation note to report
      description: >-
        Adds an internal moderation note to the report. Notes are used to
        document investigation findings, actions taken, or communication between
        moderators. Each note is timestamped and attributed to the adding
        moderator. Notes are visible only to moderators and not to the reporter
        or reported user.


        RBAC: requires Reports.Manage
      tags:
        - Admin Reports
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          text/plain:
            schema:
              type: string
        required: true
      responses:
        '200':
          description: Note successfully added to report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ReportNotFound
                message: The specified report not found
          description: The specified report not found
      security: []
  /api/v1/admin/reports/{reportId}/assign-to-self:
    post:
      summary: Assign report to yourself
      description: >-
        Assigns the current user as the moderator responsible for handling this
        report. This helps coordinate moderation efforts by showing other
        moderators that someone is actively investigating this report. Updates
        the assignedToUserId field.


        RBAC: requires Reports.Manage
      tags:
        - Admin Reports
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Report successfully assigned to current user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ReportNotFound
                message: The specified report not found
          description: The specified report not found
      security: []
  /api/v1/admin/reports/{reportId}/delete:
    delete:
      summary: Permanently delete a report
      description: >-
        Permanently removes a report from the system. This should only be used
        for invalid or spam reports. For legitimate reports that have been
        addressed, use the resolve endpoint instead to maintain moderation
        history. This action cannot be undone.


        RBAC: requires Reports.Manage
      tags:
        - Admin Reports
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Report successfully deleted from the system
          content:
            text/plain: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ReportNotFound
                message: The specified report not found
          description: The specified report not found
      security: []
  /api/v1/admin/reports/{reportId}/remove-note:
    post:
      summary: Remove moderation note from report
      description: >-
        Removes a specific moderation note from the report by its index
        position. Use this to correct mistakes or remove outdated information.
        Notes are zero-indexed, so the first note has index 0. Only valid
        indices are accepted.


        RBAC: requires Reports.Manage
      tags:
        - Admin Reports
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Zero-based index of the note to remove from the notes array
          required: true
          name: index
          in: query
          schema:
            format: int32
            type: integer
      responses:
        '200':
          description: Note successfully removed from report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ReportNotFound
                message: The specified report not found
          description: The specified report not found
      security: []
  /api/v1/admin/reports/{reportId}/reopen:
    post:
      summary: Reopen a resolved report
      description: >-
        Reopens a previously resolved report for further investigation. This
        clears the resolution status and allows the report to be reassigned and
        worked on again. Useful when initial resolution was insufficient or new
        information becomes available.


        RBAC: requires Reports.Manage
      tags:
        - Admin Reports
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Report successfully reopened
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ReportNotFound
                message: The specified report not found
          description: The specified report not found
      security: []
  /api/v1/admin/reports/{reportId}/resolve:
    post:
      summary: Mark report as resolved
      description: >-
        Marks a report as resolved/closed, indicating that action has been
        taken. The current user is recorded as the moderator who resolved the
        report. This updates the actionTakenAt timestamp and actionTakenByUserId
        fields.


        RBAC: requires Reports.Manage
      tags:
        - Admin Reports
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Report successfully resolved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ReportNotFound
                message: The specified report not found
          description: The specified report not found
      security: []
  /api/v1/admin/reports/{reportId}/unassign:
    post:
      summary: Unassign report from any moderator
      description: >-
        Removes the assignment of this report from any moderator, making it
        available for other moderators to claim. Use when unable to complete
        investigation or when transferring to another moderator. Clears the
        assignedToUserId field.


        RBAC: requires Reports.Manage
      tags:
        - Admin Reports
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Report successfully unassigned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ReportNotFound
                message: The specified report not found
          description: The specified report not found
      security: []
  /api/v1/admin/restart-ap-delivery:
    post:
      summary: Restarts ActivityPub delivery for the domain
      tags:
        - Admin ActivityPub
      parameters:
        - name: domain
          in: query
          schema:
            pattern: \S
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
      description: 'RBAC: requires Federation.Manage'
  /api/v1/admin/search:
    get:
      summary: Search for users
      description: >-
        Performs an administrative search for users with multiple filter
        criteria. Can search by user ID, account ID, username, domain, display
        name, state, email, IP address, country, or role. Supports mixed search
        across username, display name, and email simultaneously. Results include
        detailed user information and support pagination and sorting. IP
        addresses are matched exactly, and country codes should use ISO 3166-1
        alpha-2 format.


        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      parameters:
        - description: Account id
          required: false
          name: accountId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Country
          required: false
          name: country
          in: query
          schema:
            type: string
            nullable: true
        - description: Display name
          required: false
          name: displayName
          in: query
          schema:
            type: string
            nullable: true
        - description: Domain
          required: false
          name: domain
          in: query
          schema:
            type: string
            nullable: true
        - description: Email
          required: false
          name: email
          in: query
          schema:
            type: string
            nullable: true
        - description: IP address
          required: false
          name: ip
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Result kind: CHANNEL for only global channels, USER for only users,
            ALL for both. Default ALL
          required: false
          name: kind
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/Kind'
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Role
          required: false
          name: role
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/RoleId'
            nullable: true
        - description: Mixed search across username, display name or email
          required: false
          name: search
          in: query
          schema:
            type: string
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: State
          required: false
          name: state
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/UserState'
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: userId
          required: false
          name: userId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Username
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: >-
            List of users, number of users found and total number of users on
            server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchDetails'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SortingError
                message: Sort field is not supported
          description: Sort field is not supported
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/signup_requests/approve/{hash}:
    put:
      summary: Approve a signup request
      description: >-
        Approves a pending signup request and creates the user account. Sends a
        welcome email to the user upon successful account creation. If username
        conflicts occur, sends an alternative email prompting the user to choose
        a different username. If email/phone conflicts occur, the request is
        deleted as the user likely already has an account. The operation is
        logged for audit purposes.


        RBAC: requires Signups.Manage
      tags:
        - Admin Signup Requests
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Signup request approved and account created successfully
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SendEmailError
                message: Failed to send email
          description: Failed to send email
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountCreationError
                message: Failed to create the account
          description: Failed to create the account
      security: []
  /api/v1/admin/signup_requests/delete/{hash}:
    delete:
      summary: Delete a signup request
      description: >-
        Permanently removes a signup request from the system without notifying
        the user. Use this for cleaning up invalid, duplicate, or spam requests.
        Unlike rejection, this does not send any notification to the applicant.
        The request cannot be recovered after deletion.


        RBAC: requires Signups.Manage
      tags:
        - Admin Signup Requests
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Signup request successfully deleted
          content:
            application/json:
              schema: {}
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/signup_requests/list:
    get:
      summary: List pending signup requests
      description: >-
        Retrieves a paginated list of signup requests awaiting admin approval.
        Can filter by email address, request hash, or originating IP address.
        Results are sorted by creation date (newest first) by default. Only
        shows requests at the ADMIN approval step.


        RBAC:

        - requires ANY of Signups.Read, Signups.Manage
      tags:
        - Admin Signup Requests
      parameters:
        - description: Filter by email address. Returns requests with matching email.
          required: false
          name: email
          in: query
          schema:
            type: string
            nullable: true
        - description: Filter by request hash. Returns the specific request with this hash.
          required: false
          name: hash
          in: query
          schema:
            type: string
            nullable: true
        - description: Filter by IP address. Returns requests from this originating IP.
          required: false
          name: ip
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: Paginated list of signup requests with total count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupRequestResult'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/signup_requests/reject/{hash}:
    put:
      summary: Reject a signup request
      description: >-
        Rejects a pending signup request and permanently removes it from the
        queue. Sends a rejection email to the applicant with an optional reason
        for the rejection. This action is final and the user would need to
        submit a new signup request. The rejection is logged for audit purposes.


        RBAC: requires Signups.Manage
      tags:
        - Admin Signup Requests
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
        - description: >-
            Optional reason for rejection to include in the notification email.
            Helps users understand why their request was denied.
          required: false
          name: reason
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Signup request rejected and user notified
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SendEmailError
                message: Failed to send email
          description: Failed to send email
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
      security: []
  /api/v1/admin/uploads/jobs/queue/{queueName}:
    get:
      summary: List upload processing jobs in queue
      description: >-
        Retrieves upload processing jobs from a specific queue (submitted,
        in_progress, or completed). Used to monitor the status of async upload
        processing tasks such as image resizing, video encoding, or thumbnail
        generation. Supports filtering by upload type and sorting by various
        fields like submission time or processing duration.


        RBAC: requires Uploads.Read
      tags:
        - Admin Uploads
      parameters:
        - description: Queue name to retrieve jobs from (submitted, in_progress, completed)
          required: true
          name: queueName
          in: path
          schema:
            type: string
        - description: Maximum number of jobs to return. Default is 10.
          name: limit
          in: query
          schema:
            format: int32
            type: integer
        - description: Pagination offset for results. Default is 0.
          name: offset
          in: query
          schema:
            format: int32
            type: integer
        - description: Field to sort by (submission_time, processing_duration, etc.)
          name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - description: 'Sort order direction. Values: ''asc'' or ''desc''. Default is ascending.'
          name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: Filter by upload type (IMAGE, VIDEO, AUDIO, DOCUMENT)
          name: uploadType
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Upload jobs list retrieved successfully
          content:
            application/json:
              schema:
                description: List of the upload jobs
                required:
                  - list
                type: object
                properties:
                  list:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProcessJob'
                  total:
                    format: int32
                    description: Total number of jobs in the queue.
                    type: integer
                  totalJobs:
                    format: int32
                    description: Total number of jobs in the queue with specified filter.
                    type: integer
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UploadJobsInvalidSortingFields:
                  description: >-
                    Invalid sorting fields for upload jobs. Correct values are:
                    SubmissionTime, TimeInQueue, FileSize
                  value:
                    errorCode: UploadJobsInvalidSortingFields
                    message: >-
                      Invalid sorting fields for upload jobs. Correct values
                      are: SubmissionTime, TimeInQueue, FileSize
                UploadJobsInvalidOffset:
                  description: >-
                    Invalid offset for upload jobs. Must be greater or equal to
                    0
                  value:
                    errorCode: UploadJobsInvalidOffset
                    message: >-
                      Invalid offset for upload jobs. Must be greater or equal
                      to 0
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/uploads/jobs/summary:
    get:
      summary: Get upload job queue summaries
      description: >-
        Retrieves summary statistics for all upload processing queues, showing
        counts of jobs in submitted, in-progress, and completed states. Provides
        a high-level overview of the upload processing system's current workload
        and performance. Useful for monitoring system health and identifying
        processing bottlenecks.


        RBAC: requires Uploads.Read
      tags:
        - Admin Uploads
      responses:
        '200':
          description: Queue summaries retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/QueueSummary'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/uploads/search:
    get:
      summary: Search user uploads with filters
      description: >-
        Searches and retrieves uploads for a specific user with optional
        filtering by upload type (IMAGE, VIDEO, AUDIO, DOCUMENT) and tags
        (Avatar, Header, Post, etc.). Supports pagination for large result sets.
        Returns upload metadata including file information, processing status,
        and associated tags.


        RBAC: requires Uploads.Read
      tags:
        - Admin Uploads
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Filter by upload tag (Avatar, Header, Post, etc.). Omit to include
            all tags.
          required: false
          name: tag
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/UploadsTags'
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: >-
            Filter by upload type (IMAGE, VIDEO, AUDIO, DOCUMENT). Omit to
            include all types.
          required: false
          name: uploadType
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/UploadType'
            nullable: true
        - description: User ID whose uploads to search. Must be a valid USER type TypeId.
          required: true
          name: userId
          in: query
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Upload search results retrieved successfully
          content:
            application/json:
              schema:
                description: List uploads result
                required:
                  - list
                type: object
                properties:
                  list:
                    type: array
                    items:
                      $ref: '#/components/schemas/Upload'
                  total:
                    format: int64
                    type: integer
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: InvalidUploadListRequest
                message: >-
                  Invalid request to list uploads. Provide a valid userId,
                  pagination, and a supported order field (createdAt or size).
          description: >-
            Invalid request to list uploads. Provide a valid userId, pagination,
            and a supported order field (createdAt or size).
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/uploads/storage/{userId}:
    get:
      summary: Get user storage information
      description: >-
        Retrieves detailed storage usage information for a specific user,
        including total storage used, file counts by type, and storage limits.
        Useful for monitoring user storage consumption and enforcing quotas.


        RBAC: requires Uploads.Read
      tags:
        - Admin Uploads
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: User storage information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserStorage'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/admin/user/change-state:
    post:
      summary: Update user moderation state
      description: >-
        Changes the moderation state of a user (e.g., ACTIVE, SUSPENDED,
        LIMITED). This affects what actions the user can perform on the
        platform. When suspending a user, their content may be hidden and
        followers on remote servers are notified. When unsuspending, the user's
        content is restored and remote servers are updated. Administrators
        cannot change their own state. Changes are logged for audit purposes and
        can be linked to moderation reports.


        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeUserState'
        required: true
      responses:
        '200':
          description: User state successfully updated
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UserCannotBlockSelf:
                  description: A user cannot block themselves
                  value:
                    errorCode: UserCannotBlockSelf
                    message: A user cannot block themselves
                UserNotUpdated:
                  description: Failed to update the user
                  value:
                    errorCode: UserNotUpdated
                    message: Failed to update the user
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security: []
  /api/v1/admin/user/change-state-bulk:
    post:
      summary: Bulk update user moderation states
      description: >-
        Changes the moderation state for multiple users in a single optimized
        operation. Performs one bulk DB update, submits jobs in batches for
        users transitioning to or from SUSPENDED, and distributes updates
        without per-user queries.


        RBAC: requires Users.Manage
      tags:
        - Admin Accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeUserStateBulk'
        required: true
      responses:
        '200':
          description: Bulk user states updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeUsersStateResult'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserCannotBlockSelf
                message: A user cannot block themselves
          description: A user cannot block themselves
      security: []
  /api/v1/admin/user/{userId}:
    get:
      summary: Retrieve detailed user information by ID
      description: >-
        Fetches comprehensive details about a specific user including their
        account association, profile information, roles, state, statistics, and
        activity data. Requires either Users.Read or Users.Manage permission.


        RBAC:

        - requires ALL of Users.Manage

        - requires ANY of Users.Read, Users.Manage
      tags:
        - Admin Accounts
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: User details successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetails'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security: []
  /api/v1/ai-agents/assignments:
    get:
      summary: List AI agent assignments
      description: >-
        Retrieves a list of AI agent assignments filtered by assignment type and
        optional resource ID.
                    This allows querying which bots are active in specific scopes (global, forums, categories, channels).
                    Returns an array of assignments matching the specified criteria.

        RBAC:

        - requires ANY of AIAgents.Read, AIAgents.Manage
      tags:
        - AI Agents
      parameters:
        - description: |-
            Optional resource ID to filter assignments for a specific resource.
                            Required for non-GLOBAL/GROUP assignments (e.g., forum_id for FORUM type, category_id for FORUM_CATEGORY type).
                            Must be null or omitted for GLOBAL and GROUP assignment types.
          example: frm_xyz123
          required: false
          name: resourceId
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Optional assignment type to filter by. Valid values: GLOBAL, GROUP,
            FORUM,
                            FORUM_CATEGORY, GROUP_CHANNEL.
                            Determines the scope where the AI agent operates.
          example: GLOBAL
          required: false
          name: type
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/AIAgentAssignmentType'
            nullable: true
      responses:
        '200':
          description: Array of AI agent assignments matching the query criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AIAgentAssignment'
                example:
                  - assignmentId: aia_abc123
                    agentId: usr_bot456
                    assignmentType: GLOBAL
                    resourceId: null
                    groupId: null
                    createdAt: '2024-01-15T10:30:00Z'
                    updatedAt: '2024-01-15T10:30:00Z'
                  - assignmentId: aia_def789
                    agentId: usr_bot789
                    assignmentType: FORUM
                    resourceId: frm_xyz123
                    groupId: grp_abc456
                    createdAt: '2024-01-16T14:20:00Z'
                    updatedAt: '2024-01-16T14:20:00Z'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: Forbidden
                message: No access to the resource
          description: No access to the resource
      security: []
    delete:
      summary: Delete an AI agent assignment
      description: |-
        Deletes an existing AI agent assignment by its ID.
                    This deactivates the bot from its assigned scope.
                    Returns success if the assignment was deleted, or ResourceNotFound if the assignment doesn't exist.

        RBAC: requires AIAgents.Manage
      tags:
        - AI Agents
      parameters:
        - description: The TypeId of the AI agent assignment to delete
          example: aia_abc123
          required: true
          name: id
          in: query
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Assignment successfully deleted
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: Forbidden
                message: No access to the resource
          description: No access to the resource
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security: []
    post:
      summary: Create a global AI agent assignment
      description: |-
        Creates a global AI agent assignment that activates a bot platform-wide.
                    The agent must be a valid bot user (user with isBot=true).
                    Only GLOBAL assignment type is allowed in this context.
                    For group-scoped assignments, use the Group AI Agent Management API instead.

        RBAC: requires AIAgents.Manage
      tags:
        - AI Agents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AIAgentAssignmentCreate'
        required: true
      responses:
        '200':
          description: Successfully created AI agent assignment with assignment details
          content:
            application/json:
              schema:
                description: >-
                  Complete AI agent assignment record representing an active bot
                  deployment.
                          Contains the assignment configuration, timestamps, and scope information.
                          The RAG pipeline reads these assignments to enable bot interactions in their designated areas.
                required:
                  - assignmentId
                  - agentId
                  - assignmentType
                  - createdAt
                  - updatedAt
                type: object
                properties:
                  assignmentId:
                    description: Unique TypeId for this assignment
                    type: string
                    allOf:
                      - $ref: '#/components/schemas/TypeId'
                    example: aia_abc123
                  agentId:
                    description: >-
                      TypeId of the bot user assigned. References a user with
                      isBot=true.
                    type: string
                    allOf:
                      - $ref: '#/components/schemas/TypeId'
                    example: usr_bot456
                  assignmentType:
                    description: |-
                      Assignment type determining where the bot operates.
                                  Valid values: GLOBAL, GROUP, FORUM, FORUM_CATEGORY, GROUP_CHANNEL
                    type: string
                    allOf:
                      - $ref: '#/components/schemas/AIAgentAssignmentType'
                    example: FORUM
                  resourceId:
                    description: >-
                      TypeId of the specific resource this assignment is scoped
                      to.
                                  Null for GLOBAL assignments.
                                  Contains forum_id for FORUM, category_id for FORUM_CATEGORY, channel_id for GROUP_CHANNEL assignments.
                    type: string
                    allOf:
                      - $ref: '#/components/schemas/TypeId'
                    example: frm_xyz123
                    nullable: true
                  groupId:
                    description: |-
                      TypeId of the group this assignment belongs to.
                                  Present for group-scoped assignments (GROUP, FORUM, FORUM_CATEGORY, GROUP_CHANNEL).
                                  Null for GLOBAL assignments.
                    type: string
                    allOf:
                      - $ref: '#/components/schemas/TypeId'
                    example: grp_abc456
                    nullable: true
                  createdAt:
                    description: ISO 8601 timestamp when this assignment was created
                    type: string
                    allOf:
                      - $ref: '#/components/schemas/Instant'
                    example: '2024-01-15T10:30:00Z'
                  updatedAt:
                    description: ISO 8601 timestamp when this assignment was last updated
                    type: string
                    allOf:
                      - $ref: '#/components/schemas/Instant'
                    example: '2024-01-15T10:30:00Z'
                example:
                  assignmentId: aia_abc123
                  agentId: usr_bot456
                  assignmentType: GLOBAL
                  resourceId: null
                  groupId: null
                  createdAt: '2024-01-15T10:30:00Z'
                  updatedAt: '2024-01-15T10:30:00Z'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UserIsNotBot:
                  description: The user is not a bot
                  value:
                    errorCode: UserIsNotBot
                    message: The user is not a bot
                ConstraintViolation:
                  description: A request parameter constraint was violated
                  value:
                    errorCode: ConstraintViolation
                    message: A request parameter constraint was violated
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: Forbidden
                message: No access to the resource
          description: No access to the resource
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security: []
  /api/v1/ai-agents/posts:
    get:
      summary: Retrieve posts for AI agents
      description: >-
        Returns posts for AI agents. If ownerId is missing, retrieves posts from
        the global space (group_id is null) with PUBLIC visibility. Supports
        pagination and optional 'since' timestamp to fetch posts strictly newer
        than the given timestamp.


        RBAC: requires AIAgents.PostsRead
      tags:
        - AI Agents
      parameters:
        - description: Maximum number of items to return (page size). Defaults to 100.
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: >-
            Owner id. Accepts a group channel (USER) or forum category
            (CATEGORY) id
          required: false
          name: ownerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Timestamp to retrieve posts strictly newer than this (by createdAt)
          required: false
          name: since
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/Instant'
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: Posts list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/apps:
    post:
      summary: Install a new application from ZIP file
      description: >-
        Uploads and installs a new application from a ZIP archive. The
        application is created in a disabled state by default unless the
        'enable' parameter is set to true.


        RBAC: requires Apps.Manage
      tags:
        - Applications
      parameters:
        - description: >-
            Automatically enable the application after successful installation.
            Default is false.
          example: true
          required: false
          name: enable
          in: query
          schema:
            type: boolean
            nullable: true
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - file
              type: object
              properties:
                file:
                  format: binary
                  type: string
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AppNoManifest:
                  description: No manifest was provided
                  value:
                    errorCode: AppNoManifest
                    message: No manifest was provided
                AppIncorrectYamlFile:
                  description: The provided manifest file is incorrect
                  value:
                    errorCode: AppIncorrectYamlFile
                    message: The provided manifest file is incorrect
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppNotFound
                message: Application not found
          description: Application not found
      security:
        - header: []
    get:
      summary: List globally available applications
      description: >-
        Returns a list of applications available at the global entry point.
        These applications are accessible to all users.
      tags:
        - Applications
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Application'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security: []
  /api/v1/apps/enabled:
    get:
      summary: List all enabled applications
      description: >-
        Returns a list of all currently enabled applications on the platform.
        Only applications in enabled state are returned. No authentication
        required.
      tags:
        - Applications
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Application'
      security: []
  /api/v1/apps/installed:
    get:
      summary: List all installed applications
      description: >-
        Returns a list of all installed applications on the platform, including
        both enabled and disabled applications. No authentication required.
      tags:
        - Applications
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Application'
      security: []
  /api/v1/apps/user:
    get:
      summary: List user's available applications
      description: >-
        Returns a list of applications available to the authenticated user,
        including both globally available and user-specific applications.
      tags:
        - Applications
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Application'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/apps/user/{appId}:
    delete:
      summary: Remove application from user's list
      description: >-
        Removes the specified application from the authenticated user's personal
        application list.
      tags:
        - Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ConstraintViolation
                message: A request parameter constraint was violated
          description: A request parameter constraint was violated
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppNotFound
                message: Application not found
          description: Application not found
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppUpdateError
                message: Failed to update the application
          description: Failed to update the application
      security:
        - header: []
    put:
      summary: Add application to user's list
      description: >-
        Adds the specified application to the authenticated user's personal
        application list, making it available in their user-specific context.
      tags:
        - Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Returns app
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ConstraintViolation
                message: A request parameter constraint was violated
          description: A request parameter constraint was violated
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppNotFound
                message: Application not found
          description: Application not found
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppUpdateError
                message: Failed to update the application
          description: Failed to update the application
      security:
        - header: []
  /api/v1/apps/{appId}:
    put:
      summary: Update an existing application from ZIP file
      description: >-
        Updates an existing application by uploading a new ZIP archive. The
        application manifest in the ZIP must match the existing application ID.


        RBAC: requires Apps.Manage
      tags:
        - Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            Automatically enable the application after successful update.
            Default is false.
          example: false
          required: false
          name: enable
          in: query
          schema:
            type: boolean
            nullable: true
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - file
              type: object
              properties:
                file:
                  format: binary
                  type: string
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AppNoManifest:
                  description: No manifest was provided
                  value:
                    errorCode: AppNoManifest
                    message: No manifest was provided
                AppIncorrectYamlFile:
                  description: The provided manifest file is incorrect
                  value:
                    errorCode: AppIncorrectYamlFile
                    message: The provided manifest file is incorrect
                ConstraintViolation:
                  description: A request parameter constraint was violated
                  value:
                    errorCode: ConstraintViolation
                    message: A request parameter constraint was violated
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppNotFound
                message: Application not found
          description: Application not found
      security:
        - header: []
    get:
      summary: Get application details by ID
      description: >-
        Returns the complete application definition including manifest, routes,
        and configuration for the specified application ID.
      tags:
        - Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ConstraintViolation
                message: A request parameter constraint was violated
          description: A request parameter constraint was violated
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppNotFound
                message: Application not found
          description: Application not found
      security: []
    delete:
      summary: Delete an application
      description: >-
        Permanently deletes an application from the platform. The application
        cannot be deleted if it's set as default for any routes. This operation
        is irreversible.


        RBAC: requires Apps.Manage
      tags:
        - Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AppIsDefault:
                  description: The application is set as default
                  value:
                    errorCode: AppIsDefault
                    message: The application is set as default
                ConstraintViolation:
                  description: A request parameter constraint was violated
                  value:
                    errorCode: ConstraintViolation
                    message: A request parameter constraint was violated
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppNotFound
                message: Application not found
          description: Application not found
      security:
        - header: []
  /api/v1/apps/{appId}/data:
    get:
      summary: Query application data with filters
      description: >-
        Retrieves application data entries based on filter criteria. Can filter
        by data type, tags (multiple tags are AND-ed), and owner. The user must
        have read permissions for the specified owner if filtering by owner.
        Returns all matching entries for the application. Without filters,
        returns all data the user has permission to access.
      tags:
        - Application Data
      parameters:
        - description: Application ID to query data for. Must be a valid APP type TypeId.
          required: true
          name: appId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            Filter by owner ID (user, group, user:group, or 'platform').
            Requires read permission.
          required: false
          name: owner
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Filter by tags. Comma-separated list. Returns entries that have ALL
            specified tags.
          required: false
          name: tags
          in: query
          schema:
            type: array
            items:
              type: string
        - description: Filter by data type. Returns only entries with this exact type.
          required: false
          name: type
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: List of matching application data entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppData'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                AppDataNoPermission:
                  description: No permission to access application data
                  value:
                    errorCode: AppDataNoPermission
                    message: No permission to access application data
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppDataNotFound
                message: The specified application data not found
          description: The specified application data not found
      security:
        - header: []
    post:
      summary: Create new application data entry
      description: >-
        Creates a new data entry for the specified application. The data can be
        owned by a user, group, user within a group context, or the platform
        itself. Ownership determines access permissions. The data structure is
        flexible, supporting any JSON content with optional type categorization
        and tags for filtering.
      tags:
        - Application Data
      parameters:
        - description: Application ID that owns this data. Must be a valid APP type TypeId.
          required: true
          name: appId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataCreate'
        required: true
      responses:
        '200':
          description: Application data successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppData'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppDataNotCreated
                message: Failed to create application data
          description: Failed to create application data
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                AppDataNoPermission:
                  description: No permission to access application data
                  value:
                    errorCode: AppDataNoPermission
                    message: No permission to access application data
          description: Forbidden
      security:
        - header: []
  /api/v1/apps/{appId}/data/{id}:
    put:
      summary: Update existing application data
      description: >-
        Updates an existing data entry for the application. The user must have
        manage permissions for the data owner (user/group). The ownership cannot
        be changed during update - the new ownerId must match the existing one.
        Updates the data content, type, and tags while preserving ownership.
      tags:
        - Application Data
      parameters:
        - description: >-
            Application ID that owns this data. Must match the data's
            application.
          required: true
          name: appId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Data entry ID to update. Must be a valid APP_DATA type TypeId.
          required: true
          name: id
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataCreate'
        required: true
      responses:
        '200':
          description: Application data successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppData'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppDataNotUpdated
                message: Failed to update application data
          description: Failed to update application data
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                AppDataNoPermission:
                  description: No permission to access application data
                  value:
                    errorCode: AppDataNoPermission
                    message: No permission to access application data
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppDataNotFound
                message: The specified application data not found
          description: The specified application data not found
      security:
        - header: []
    delete:
      summary: Delete application data entry
      description: >-
        Permanently deletes a data entry from the application storage. The user
        must have manage permissions for the data owner. This operation cannot
        be undone. All associated metadata including tags and type information
        is also removed.
      tags:
        - Application Data
      parameters:
        - description: >-
            Application ID that owns this data. Must match the data's
            application.
          required: true
          name: appId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Data entry ID to delete. Must be a valid APP_DATA type TypeId.
          required: true
          name: id
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Application data successfully deleted
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppDataNotDeleted
                message: Failed to delete application data
          description: Failed to delete application data
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                AppDataNoPermission:
                  description: No permission to access application data
                  value:
                    errorCode: AppDataNoPermission
                    message: No permission to access application data
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppDataNotFound
                message: The specified application data not found
          description: The specified application data not found
      security:
        - header: []
  /api/v1/apps/{appId}/default:
    put:
      summary: Set application as platform default
      description: >-
        Sets the specified application as the default handler for its declared
        routes at the platform level. This affects all users who haven't set
        their own defaults.


        RBAC: requires Apps.Manage
      tags:
        - Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ConstraintViolation
                message: A request parameter constraint was violated
          description: A request parameter constraint was violated
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppNotFound
                message: Application not found
          description: Application not found
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppUpdateError
                message: Failed to update the application
          description: Failed to update the application
      security: []
  /api/v1/apps/{appId}/disable:
    put:
      summary: Disable an application
      description: >-
        Disables an enabled application, removing its routes and functionality
        from user access. The application cannot be disabled if it's set as
        default for any routes.


        RBAC: requires Apps.Manage
      tags:
        - Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AppIsDisabled:
                  description: The application is disabled
                  value:
                    errorCode: AppIsDisabled
                    message: The application is disabled
                AppIsDefault:
                  description: The application is set as default
                  value:
                    errorCode: AppIsDefault
                    message: The application is set as default
                ConstraintViolation:
                  description: A request parameter constraint was violated
                  value:
                    errorCode: ConstraintViolation
                    message: A request parameter constraint was violated
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppUpdateError
                message: Failed to update the application
          description: Failed to update the application
      security:
        - header: []
  /api/v1/apps/{appId}/enable:
    put:
      summary: Enable an application
      description: >-
        Enables a disabled application, making its routes and functionality
        available to users. The application must not already be enabled.


        RBAC: requires Apps.Manage
      tags:
        - Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AppIsEnabled:
                  description: The application is enabled
                  value:
                    errorCode: AppIsEnabled
                    message: The application is enabled
                ConstraintViolation:
                  description: A request parameter constraint was violated
                  value:
                    errorCode: ConstraintViolation
                    message: A request parameter constraint was violated
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppUpdateError
                message: Failed to update the application
          description: Failed to update the application
      security:
        - header: []
  /api/v1/apps/{appId}/stats:
    get:
      summary: Get application with usage statistics
      description: >-
        Returns the application definition along with usage statistics including
        install count, active users, and other metrics.
      tags:
        - Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationWithStats'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ConstraintViolation
                message: A request parameter constraint was violated
          description: A request parameter constraint was violated
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppNotFound
                message: Application not found
          description: Application not found
      security: []
  /api/v1/apps/{appId}/user-default:
    put:
      summary: Set application as user's default
      description: >-
        Sets the specified application as the default handler for its declared
        routes for the authenticated user. This overrides platform-level
        defaults for this user.
      tags:
        - Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ConstraintViolation
                message: A request parameter constraint was violated
          description: A request parameter constraint was violated
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppNotFound
                message: Application not found
          description: Application not found
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppUpdateError
                message: Failed to update the application
          description: Failed to update the application
      security:
        - header: []
    delete:
      summary: Remove user's default application
      description: >-
        Removes the user's default application setting for the specified
        application's routes, reverting to platform defaults.
      tags:
        - Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ConstraintViolation
                message: A request parameter constraint was violated
          description: A request parameter constraint was violated
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppNotFound
                message: Application not found
          description: Application not found
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppUpdateError
                message: Failed to update the application
          description: Failed to update the application
      security:
        - header: []
  /api/v1/block:
    get:
      summary: List of blocked users
      description: >-
        Returns a paginated list of all users that the authenticated user has
        blocked. Results are ordered by block date (most recent first) and
        include user profile information.
      tags:
        - Blocks
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
      security:
        - header: []
  /api/v1/block/by:
    get:
      summary: List of users who blocked you
      description: >-
        Returns a paginated list of users who have blocked the authenticated
        user. This information helps understand why certain interactions may be
        restricted. Results are ordered by block date and include basic user
        information.
      tags:
        - Blocks
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
      security:
        - header: []
  /api/v1/block/{userId}:
    delete:
      summary: Unblock previously blocked user
      description: >-
        Removes a block on a user, allowing interactions to resume. For remote
        users, sends an Undo Block activity via ActivityPub. The user must
        currently be blocked for this operation to succeed.
      tags:
        - Blocks
      parameters:
        - description: >-
            User ID to unblock. Must be a valid USER type TypeId that is
            currently blocked.
          name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UserCannotBlockSelf:
                  description: A user cannot block themselves
                  value:
                    errorCode: UserCannotBlockSelf
                    message: A user cannot block themselves
                UserIsNotBlocked:
                  description: The specified user is not blocked
                  value:
                    errorCode: UserIsNotBlocked
                    message: The specified user is not blocked
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security:
        - header: []
    post:
      summary: Block specific user
      description: >-
        Blocks a user, preventing all interactions between you and the blocked
        user. This action automatically unfollows both users from each other,
        removes any reposts, and removes any existing mute. For remote users,
        sends a Block activity via ActivityPub. Cannot block yourself.
      tags:
        - Blocks
      parameters:
        - description: User ID to block. Must be a valid USER type TypeId.
          name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UserCannotBlockSelf:
                  description: A user cannot block themselves
                  value:
                    errorCode: UserCannotBlockSelf
                    message: A user cannot block themselves
                UserAlreadyBlocked:
                  description: The specified user is already blocked
                  value:
                    errorCode: UserAlreadyBlocked
                    message: The specified user is already blocked
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security:
        - header: []
  /api/v1/custom_emojis:
    get:
      summary: Get emojis by shortcodes or categories
      description: >-
        Retrieves emojis by exact shortcodes and/or by exact categories from
        cache. Multiple values can be requested in a single call using comma
        separation. If both parameters are provided, the union of results is
        returned. Returns paginated response with items (current page results),
        total (count matching filter), and totalItems (total emojis in system).
      tags:
        - Emoji
      parameters:
        - description: Exact category name(s). Multiple values comma-separated
          example: Cats,Dogs
          name: category
          required: false
          in: query
          schema:
            type: array
            items:
              type: string
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Exact shortcode(s) of emoji. Multiple values comma-separated
          example: aaaa,AAAAAA
          name: shortcode
          required: false
          in: query
          schema:
            type: array
            items:
              type: string
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: Paginated emoji results
          content:
            application/json:
              example:
                items:
                  - shortcode: aaaa
                    url: >-
                      https://files.mastodon.social/custom_emojis/images/000/007/118/original/aaaa.png
                    static_url: >-
                      https://files.mastodon.social/custom_emojis/images/000/007/118/static/aaaa.png
                    visibleInPicker: true
                    category: Cats
                  - shortcode: AAAAAA
                    url: >-
                      https://files.mastodon.social/custom_emojis/images/000/071/387/original/AAAAAA.png
                    static_url: >-
                      https://files.mastodon.social/custom_emojis/images/000/071/387/static/AAAAAA.png
                    visibleInPicker: true
                    category: Blobs
                total: 2
                totalItems: 100
              schema:
                $ref: '#/components/schemas/EmojiPaginatedResponse'
      security: []
    delete:
      summary: Delete emojis
      description: >-
        Deletes custom emojis by shortcode or category. Can delete multiple
        emojis at once using comma-separated values. Either shortcode or
        category must be provided. Returns the count of deleted emojis. Requires
        Emojis.Manage permission (admin only).


        RBAC: requires Emojis.Manage
      tags:
        - Emoji
      parameters:
        - description: You can provide multiple categories as comma-separated values
          example: '?category=Cats,Dogs'
          name: category
          required: false
          in: query
          schema:
            type: array
            items:
              type: string
            nullable: true
        - description: You can provide multiple shortcodes as comma-separated values
          example: '?shortcode=aaa,AAA'
          name: shortcode
          required: false
          in: query
          schema:
            type: array
            items:
              type: string
            nullable: true
      responses:
        '200':
          description: Number of deleted emojis
          content:
            plain/text:
              example: '3'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
    post:
      summary: Create emoji from URL
      description: >-
        Creates a custom emoji by downloading from provided URLs. The emoji file
        is downloaded, processed, and stored locally. Supports overwriting
        existing emojis with the same shortcode. Can specify category,
        visibility, and domain for federated emojis. Requires Emojis.Manage
        permission (admin only).


        RBAC: requires Emojis.Manage
      tags:
        - Emoji
      parameters:
        - description: Should existing emojis be overwritten if shortcode matches
          name: overwrite
          required: false
          schema:
            type: boolean
          in: query
      requestBody:
        description: >-
          Json object with the emoji data: shortcode, category, url, staticUrl,
          visibleInPicker
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Emoji'
        required: true
      responses:
        '200':
          description: json object with the emoji data
          content:
            application/json:
              example: |2-

                                      {
                                        "shortcode": "aaaa",
                                        "url": "https://files.mastodon.social/custom_emojis/images/000/007/118/original/aaaa.png",
                                        "static_url": "https://files.mastodon.social/custom_emojis/images/000/007/118/static/aaaa.png",
                                        "visibleInPicker": true
                                        "category": "Cats",
                                        "domain": "mastodon.social"
                                      }
                                    ]
                                 
              schema:
                $ref: '#/components/schemas/Emoji'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                EmojiErrorProcessing:
                  description: An error occurred while processing the emoji file
                  value:
                    errorCode: EmojiErrorProcessing
                    message: An error occurred while processing the emoji file
                EmojiInvalidFormat:
                  description: The provided emoji file format is invalid
                  value:
                    errorCode: EmojiInvalidFormat
                    message: The provided emoji file format is invalid
                EmojiNoStreams:
                  description: 'Invalid file format: no streams found'
                  value:
                    errorCode: EmojiNoStreams
                    message: 'Invalid file format: no streams found'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EmojiErrorCreating
                message: Failed to create the emoji
          description: Failed to create the emoji
      security: []
  /api/v1/custom_emojis/categories:
    get:
      summary: List custom emoji categories
      description: >-
        Returns distinct non-empty categories. Supports optional query and
        pagination.


        RBAC: requires Emojis.Manage
      tags:
        - Emoji
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Filter categories by substring
          name: q
          required: false
          in: query
          schema:
            type: string
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of categories
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
      security: []
  /api/v1/custom_emojis/export:
    get:
      summary: Export emojis to ZIP
      description: >-
        Exports emojis from a specific category as a ZIP archive. The ZIP
        contains all emoji files from the specified category. Useful for backup
        or migration purposes. Returns 404 if no emojis found in the category.
        Requires Emojis.Manage permission (admin only).


        RBAC: requires Emojis.Manage
      tags:
        - Emoji
      parameters:
        - description: Category of the emojis to export
          name: category
          required: false
          schema:
            type: string
          in: query
      responses:
        '200':
          description: Zip file with the emojis
          content:
            application/octet-stream: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EmojiNotFound
                message: The specified emoji not found
          description: The specified emoji not found
      security: []
  /api/v1/custom_emojis/import:
    post:
      summary: Bulk import emojis from ZIP
      description: >-
        Imports multiple emojis from a ZIP archive. Filenames (without
        extension) become emoji shortcodes. All imported emojis share the same
        category and visibility settings. Images are automatically resized to
        128x128 if larger. Animated GIFs are preserved with static versions
        generated. Supports batch overwriting of existing emojis. Requires
        Emojis.Manage permission (admin only).


        RBAC: requires Emojis.Manage
      tags:
        - Emoji
      parameters:
        - description: Category of the imported emojis
          name: category
          required: true
          schema:
            type: string
          in: query
        - name: domain
          in: query
          schema:
            type: string
            nullable: true
        - description: Should existing emojis be overwritten if any of the shortcodes match
          name: overwrite
          required: false
          schema:
            type: boolean
          in: query
        - description: Whether the imported emojis should be visible in the picker
          name: visible
          required: true
          in: query
          schema:
            type: boolean
      requestBody:
        description: Zip file with the emojis.
        required: true
        content:
          multipart/form-data:
            schema:
              required:
                - file
              type: object
              properties:
                file:
                  format: binary
                  type: string
      responses:
        '200':
          description: Array of json objects with the emoji data
          content:
            application/json:
              example:
                - shortcode: aaaa
                  url: >-
                    https://files.mastodon.social/custom_emojis/images/000/007/118/original/aaaa.png
                  static_url: >-
                    https://files.mastodon.social/custom_emojis/images/000/007/118/static/aaaa.png
                  visibleInPicker: true
                  category: Cats
                - shortcode: AAAAAA
                  url: >-
                    https://files.mastodon.social/custom_emojis/images/000/071/387/original/AAAAAA.png
                  static_url: >-
                    https://files.mastodon.social/custom_emojis/images/000/071/387/static/AAAAAA.png
                  visibleInPicker: true
                  category: Blobs
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Emoji'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                EmojiErrorProcessing:
                  description: An error occurred while processing the emoji file
                  value:
                    errorCode: EmojiErrorProcessing
                    message: An error occurred while processing the emoji file
                EmojiInvalidFormat:
                  description: The provided emoji file format is invalid
                  value:
                    errorCode: EmojiInvalidFormat
                    message: The provided emoji file format is invalid
                EmojiNoStreams:
                  description: 'Invalid file format: no streams found'
                  value:
                    errorCode: EmojiNoStreams
                    message: 'Invalid file format: no streams found'
                EmojiImportingError:
                  description: An error occurred while importing the emoji
                  value:
                    errorCode: EmojiImportingError
                    message: An error occurred while importing the emoji
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security: []
  /api/v1/custom_emojis/import/upload:
    post:
      summary: Bulk import emojis from ZIP upload
      description: >-
        Imports multiple emojis from a ZIP archive that was previously uploaded
        via /uploads. Filenames (without extension) become emoji shortcodes. All
        imported emojis share the same category and visibility settings. Images
        are automatically resized to 128x128 if larger. Animated GIFs are
        preserved with static versions generated. Supports batch overwriting of
        existing emojis.


        RBAC: requires Emojis.Manage
      tags:
        - Emoji
      parameters:
        - description: Category of the imported emojis
          name: category
          required: true
          schema:
            type: string
          in: query
        - name: domain
          in: query
          schema:
            type: string
            nullable: true
        - description: Should existing emojis be overwritten if any of the shortcodes match
          name: overwrite
          required: false
          schema:
            type: boolean
          in: query
        - description: ID of the previously created upload containing the ZIP archive
          name: uploadId
          required: true
          in: query
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Whether the imported emojis should be visible in the picker
          name: visible
          required: true
          schema:
            type: boolean
          in: query
      responses:
        '200':
          description: Array of json objects with the emoji data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Emoji'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                EmojiErrorProcessing:
                  description: An error occurred while processing the emoji file
                  value:
                    errorCode: EmojiErrorProcessing
                    message: An error occurred while processing the emoji file
                EmojiInvalidFormat:
                  description: The provided emoji file format is invalid
                  value:
                    errorCode: EmojiInvalidFormat
                    message: The provided emoji file format is invalid
                EmojiNoStreams:
                  description: 'Invalid file format: no streams found'
                  value:
                    errorCode: EmojiNoStreams
                    message: 'Invalid file format: no streams found'
                EmojiImportingError:
                  description: An error occurred while importing the emoji
                  value:
                    errorCode: EmojiImportingError
                    message: An error occurred while importing the emoji
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security: []
  /api/v1/custom_emojis/search:
    get:
      summary: Search emojis by partial shortcode or category
      description: >-
        Searches for emojis whose shortcodes or categories contain provided
        substrings. Useful for autocomplete functionality. Multiple searches can
        be performed in one request by passing comma-separated values. If no
        parameters provided, returns all emojis from cache. Returns paginated
        response with items (current page results), total (count matching
        filter), and totalItems (total emojis in system).
      tags:
        - Emoji
      parameters:
        - description: Category substring(s) to search. Comma-separated
          example: Cat,Blob
          name: category
          required: false
          in: query
          schema:
            type: array
            items:
              type: string
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Shortcode substring(s) to search. Comma-separated
          example: aaa,AAA
          name: shortcode
          required: false
          in: query
          schema:
            type: array
            items:
              type: string
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: Paginated emoji search results
          content:
            application/json:
              example:
                items:
                  - shortcode: aaaa
                    url: >-
                      https://files.mastodon.social/custom_emojis/images/000/007/118/original/aaaa.png
                    static_url: >-
                      https://files.mastodon.social/custom_emojis/images/000/007/118/static/aaaa.png
                    visibleInPicker: true
                    category: Cats
                  - shortcode: AAAAAA
                    url: >-
                      https://files.mastodon.social/custom_emojis/images/000/071/387/original/AAAAAA.png
                    static_url: >-
                      https://files.mastodon.social/custom_emojis/images/000/071/387/static/AAAAAA.png
                    visibleInPicker: true
                    category: Blobs
                total: 15
                totalItems: 100
              schema:
                $ref: '#/components/schemas/EmojiPaginatedResponse'
      security: []
  /api/v1/custom_emojis/upload:
    post:
      summary: Upload emoji from existing upload
      description: >-
        Processes an existing upload (created via /uploads) as a custom emoji.
        Clients must first create an upload and PUT the file to the returned
        URL, then call this endpoint with the uploadId.


        RBAC: requires Emojis.Manage
      tags:
        - Emoji
      parameters:
        - description: Category of the emoji
          name: category
          required: true
          schema:
            type: string
          in: query
        - name: domain
          in: query
          schema:
            type: string
            nullable: true
        - description: Should existing emojis be overwritten if shortcode matches
          name: overwrite
          required: false
          schema:
            type: boolean
          in: query
        - description: Shortcode of the emoji
          name: shortcode
          required: true
          schema:
            type: string
          in: query
        - description: ID of the previously created upload containing the emoji file
          name: uploadId
          required: true
          in: query
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Whether the emoji should be visible in the picker
          name: visible
          required: true
          schema:
            type: boolean
          in: query
      responses:
        '200':
          description: json object with the emoji data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Emoji'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                EmojiErrorProcessing:
                  description: An error occurred while processing the emoji file
                  value:
                    errorCode: EmojiErrorProcessing
                    message: An error occurred while processing the emoji file
                EmojiInvalidFormat:
                  description: The provided emoji file format is invalid
                  value:
                    errorCode: EmojiInvalidFormat
                    message: The provided emoji file format is invalid
                EmojiNoStreams:
                  description: 'Invalid file format: no streams found'
                  value:
                    errorCode: EmojiNoStreams
                    message: 'Invalid file format: no streams found'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security: []
  /api/v1/custom_emojis/{shortcode}:
    patch:
      summary: Partially update emoji metadata
      description: >-
        Updates emoji metadata fields without requiring file upload. Supports
        updating category, visibility and domain. Requires Emojis.Manage
        permission.


        RBAC: requires Emojis.Manage
      tags:
        - Emoji
      parameters:
        - description: Emoji shortcode
          name: shortcode
          required: true
          in: path
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmojiPatchRequest'
        required: true
      responses:
        '200':
          description: Updated emoji
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Emoji'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EmojiNotFound
                message: The specified emoji not found
          description: The specified emoji not found
      security: []
  /api/v1/data:
    get:
      summary: Query platform data with filters
      description: >-
        Retrieves platform-level data entries based on filter criteria. Can
        filter by type, tags (multiple tags are AND-ed), and owner. When
        filtering by owner, requires Data.Manage permission for that owner.
        Returns all matching entries not tied to any specific application.
        Without filters, returns all platform data the user has permission to
        access.
      tags:
        - Platform Data
      parameters:
        - description: >-
            Filter by owner ID (user, group, user:group, or 'platform').
            Requires manage permission.
          required: false
          name: owner
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Filter by tags. Comma-separated list. Returns entries that have ALL
            specified tags.
          required: false
          name: tags
          in: query
          schema:
            type: array
            items:
              type: string
        - description: Filter by data type. Returns only entries with this exact type.
          required: false
          name: type
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: List of matching platform data entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppData'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                AppDataNoPermission:
                  description: No permission to access application data
                  value:
                    errorCode: AppDataNoPermission
                    message: No permission to access application data
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppDataNotFound
                message: The specified application data not found
          description: The specified application data not found
      security:
        - header: []
    post:
      summary: Create new platform data entry
      description: >-
        Creates a new data entry at the platform level, not associated with any
        specific application. The data can be owned by users, groups, or the
        platform itself. Requires Data.Manage permission for the specified
        owner. Supports flexible JSON content with optional type categorization
        and tags.
      tags:
        - Platform Data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataCreate'
        required: true
      responses:
        '200':
          description: Data entry successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppData'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppDataNotCreated
                message: Failed to create application data
          description: Failed to create application data
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                AppDataNoPermission:
                  description: No permission to access application data
                  value:
                    errorCode: AppDataNoPermission
                    message: No permission to access application data
          description: Forbidden
      security:
        - header: []
  /api/v1/data/{id}:
    put:
      summary: Update existing platform data
      description: >-
        Updates an existing platform-level data entry. Requires Data.Manage
        permission for the data owner. The ownership cannot be changed - the new
        ownerId must match the existing one. Updates the content, type, and tags
        while preserving the original ownership.
      tags:
        - Platform Data
      parameters:
        - description: Data entry ID to update. Must be a valid APP_DATA type TypeId.
          required: true
          name: id
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataCreate'
        required: true
      responses:
        '200':
          description: Data entry successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppData'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppDataNotUpdated
                message: Failed to update application data
          description: Failed to update application data
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                AppDataNoPermission:
                  description: No permission to access application data
                  value:
                    errorCode: AppDataNoPermission
                    message: No permission to access application data
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppDataNotFound
                message: The specified application data not found
          description: The specified application data not found
      security:
        - header: []
    delete:
      summary: Delete platform data entry
      description: >-
        Permanently deletes a platform-level data entry. Requires Data.Manage
        permission for the data owner. This operation is irreversible and
        removes all associated metadata including type and tags. Use with
        caution as deleted data cannot be recovered.
      tags:
        - Platform Data
      parameters:
        - description: Data entry ID to delete. Must be a valid APP_DATA type TypeId.
          required: true
          name: id
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Data entry successfully deleted
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppDataNotDeleted
                message: Failed to delete application data
          description: Failed to delete application data
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                AppDataNoPermission:
                  description: No permission to access application data
                  value:
                    errorCode: AppDataNoPermission
                    message: No permission to access application data
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppDataNotFound
                message: The specified application data not found
          description: The specified application data not found
      security:
        - header: []
  /api/v1/devices:
    put:
      summary: Register or update a device for push notifications
      tags:
        - User Devices
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceRegistrationRequest'
        required: true
      responses:
        '200':
          description: Device stored
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
    get:
      summary: Get all registered devices for the current user
      tags:
        - User Devices
      responses:
        '200':
          description: List of devices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserDevice'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/devices/all:
    delete:
      summary: Delete all registered devices for the current user
      tags:
        - User Devices
      responses:
        '204':
          description: Devices deleted
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/devices/{deviceId}:
    delete:
      summary: Delete a registered device for the current user
      tags:
        - User Devices
      parameters:
        - name: deviceId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Device deleted
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/domain-block:
    get:
      summary: List blocked domains (Public)
      description: >-
        Returns the list of blocked domains with sensitive fields removed.
        Actual visibility and whether reasons are shown depend on instance
        settings.
      tags:
        - Domain Blocks
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: Successfully retrieved public list of blocked domains
          content:
            application/json:
              examples:
                Public blocked domains:
                  value:
                    - domain: sp**.e*****e
                      publicComment: ''
                      state: SUSPEND
                      rejectMedia: true
                      rejectReports: true
                      privateComment: ''
                      obfuscate: true
                      createdAt: '2024-01-15T10:30:00Z'
                      updatedAt: '2024-01-15T10:30:00Z'
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BlockedDomain'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/drafts:
    get:
      summary: Get all drafts for the current user
      description: >-
        Returns a list of all drafts created by the authenticated user, sorted
        by last modification date.
      tags:
        - Drafts
      responses:
        '200':
          description: List of drafts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Draft'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
    post:
      summary: Create a new draft
      description: >-
        Creates a new draft that can be saved and published later. Drafts can be
        associated with users, groups, or categories, and can be linked to
        existing posts for editing.
      tags:
        - Drafts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDraftRequest'
      responses:
        '200':
          description: The created draft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Draft'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/drafts/owner/{ownerId}:
    get:
      summary: Get all drafts for a specific owner
      description: >-
        Returns all drafts associated with a specific owner (user or category).
        Only drafts owned by the authenticated user are returned.
      tags:
        - Drafts
      parameters:
        - name: ownerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: List of drafts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Draft'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/drafts/post/{postId}:
    get:
      summary: Get a draft for a specific post
      description: >-
        Retrieves a draft associated with a specific post ID. Used for editing
        existing posts. Only the draft owner can access it.
      tags:
        - Drafts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: The draft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Draft'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: DraftNotFound
                message: The specified draft not found
          description: The specified draft not found
      security:
        - header: []
  /api/v1/drafts/{draftId}:
    put:
      summary: Update an existing draft
      description: >-
        Updates the content, title, privacy settings, or tags of an existing
        draft. Only the draft owner can update it.
      tags:
        - Drafts
      parameters:
        - name: draftId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDraftRequest'
      responses:
        '200':
          description: The updated draft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Draft'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: DraftNotFound
                message: The specified draft not found
          description: The specified draft not found
      security:
        - header: []
    get:
      summary: Get a draft by ID
      description: >-
        Retrieves a specific draft by its unique identifier. Only the draft
        owner can access it.
      tags:
        - Drafts
      parameters:
        - name: draftId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: The draft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Draft'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: DraftNotFound
                message: The specified draft not found
          description: The specified draft not found
      security:
        - header: []
    delete:
      summary: Delete a draft
      description: >-
        Permanently deletes a draft. Only the draft owner can delete it. This
        action cannot be undone.
      tags:
        - Drafts
      parameters:
        - name: draftId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: DraftNotFound
                message: The specified draft not found
          description: The specified draft not found
      security:
        - header: []
  /api/v1/drafts/{draftId}/publish:
    post:
      summary: Publish a draft as a post
      description: >-
        Publishes a draft, converting it into a public post. The draft is
        deleted after successful publication. Only the draft owner can publish
        it.
      tags:
        - Drafts
      parameters:
        - name: draftId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: The published post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: DraftNotFound
                message: The specified draft not found
          description: The specified draft not found
      security:
        - header: []
  /api/v1/events:
    get:
      summary: Get public events or user-specific events
      description: >-
        Returns public events for unauthenticated users, or events for a
        specific user/owner for authenticated users. Supports filtering by
        organizer or owner.
      tags:
        - Events
      parameters:
        - description: List specific group's events
          required: false
          name: groupId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Show no more than the given number of events
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: An offset to show events starting from
          required: false
          name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: List specific user's events
          required: false
          name: organizerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: List specific user's events
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
        - description: Include translation
          required: false
          name: withTranslation
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/Language'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserIdOrUserNameMissing
                message: The userId or userName must be provided
          description: The userId or userName must be provided
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security:
        - header: []
    post:
      summary: Create a new event
      description: >-
        Creates a new event with specified details including title, description,
        date/time, location, and privacy settings. The authenticated user
        becomes the event organizer.
      tags:
        - Events
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEvent'
        required: true
      responses:
        '200':
          description: Event object just created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: NotGroupMember
                message: The user must be a member of the group
          description: The user must be a member of the group
      security:
        - header: []
  /api/v1/events/calendar/g/{groupname}.ics:
    get:
      summary: Export group's public calendar
      description: >-
        Exports a group's public events as an ICS (iCalendar) file. Only
        available if the group has enabled public calendar export in their
        settings.
      tags:
        - Events
      parameters:
        - description: Group name of the group of public calendar
          required: true
          name: groupname
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Calendar in ICS format
          content:
            text/calendar:
              schema:
                format: binary
                type: string
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/events/calendar/p/{id}.ics:
    get:
      summary: Export private calendar
      description: >-
        Exports a user's or group's private calendar using a unique private ID.
        Includes both public and private events based on settings.
      tags:
        - Events
      parameters:
        - description: Private calendar id
          required: true
          name: id
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Calendar in ICS format
          content:
            text/calendar:
              schema:
                format: binary
                type: string
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/events/calendar/u/{username}.ics:
    get:
      summary: Export user's public calendar
      description: >-
        Exports a user's public events as an ICS (iCalendar) file. Only
        available if the user has enabled public calendar export in their
        settings.
      tags:
        - Events
      parameters:
        - description: Public calendar user's username
          required: true
          name: username
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Calendar in ICS format
          content:
            text/calendar:
              schema:
                format: binary
                type: string
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/events/following:
    get:
      summary: Get events from followed users
      description: >-
        Returns events organized by users that the authenticated user follows.
        Supports pagination and optional translations.
      tags:
        - Events
      parameters:
        - description: Show no more than the given number of events
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: An offset to show events starting from
          required: false
          name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Include translation
          required: false
          name: withTranslation
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/Language'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/events/my:
    get:
      summary: Get authenticated user's events
      description: >-
        Returns events for the authenticated user with various filtering options
        including past events, organized events, and events pending response.
      tags:
        - Events
      parameters:
        - description: Show no more than the given number of events
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: List not yet responded events only
          required: false
          name: notRespondedOnly
          in: query
          schema:
            type: boolean
            nullable: true
        - description: An offset to show events starting from
          required: false
          name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: List events current user has organized
          required: false
          name: organizedOnly
          in: query
          schema:
            type: boolean
            nullable: true
        - description: List current user's past events only
          required: false
          name: past
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include translation
          required: false
          name: withTranslation
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/Language'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/events/settings:
    get:
      summary: Get event calendar settings
      description: >-
        Retrieves calendar export settings for the authenticated user or a
        specified group, including public/private calendar visibility and export
        options.
      tags:
        - Events
      parameters:
        - description: Group ID for groups
          required: false
          name: ownerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsSettings'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/events/settings/regeneratePrivateId:
    post:
      summary: Regenerate private calendar ID
      description: >-
        Generates a new unique ID for the private calendar URL. This invalidates
        the previous private calendar link.
      tags:
        - Events
      parameters:
        - description: Group ID for groups
          required: false
          name: ownerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: Newly generated unique ID for private calendar
          content:
            text/plain:
              schema:
                type: string
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/events/settings/update:
    post:
      summary: Update event calendar settings
      description: >-
        Updates calendar export settings including public/private calendar
        visibility, detail level, and export scope.
      tags:
        - Events
      parameters:
        - description: Group ID for groups
          required: false
          name: ownerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEventsSettings'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsSettings'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventsSettingsInvalidExportValue
                message: Invalid exportEvents value
          description: Invalid exportEvents value
      security:
        - header: []
  /api/v1/events/{eventId}:
    put:
      summary: Update event details
      description: >-
        Updates an existing event's information including title, description,
        date/time, location, and privacy settings. Only the event organizer can
        update the event.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEvent'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: NotGroupMember
                message: The user must be a member of the group
          description: The user must be a member of the group
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventNotFound
                message: The specified event not found
          description: The specified event not found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventConflictingUpdate
                message: Conflicting event update
          description: Conflicting event update
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventUpdateError
                message: Unable to update the event
          description: Unable to update the event
      security:
        - header: []
    get:
      summary: Get event details by ID
      description: >-
        Retrieves detailed information about a specific event including attendee
        status, statistics, and optional translations.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Include translation
          required: false
          name: withTranslation
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/Language'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventNotFound
                message: The specified event not found
          description: The specified event not found
      security:
        - header: []
    delete:
      summary: Delete an event
      description: >-
        Soft deletes an event, marking it as cancelled. The event is not
        permanently removed and can still be viewed as deleted. Only the event
        organizer can delete the event.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Event has been deleted successfully
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventNotFound
                message: The specified event not found
          description: The specified event not found
      security:
        - header: []
  /api/v1/events/{eventId}.ics:
    get:
      summary: Export event as ICS file
      description: >-
        Exports a single event in ICS (iCalendar) format for import into
        calendar applications.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Calendar in ICS format
          content:
            text/calendar:
              schema:
                format: binary
                type: string
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/events/{eventId}/accept:
    post:
      summary: Accept private event invitation
      description: >-
        Accepts an invitation to a private event, confirming attendance. Only
        invited users can accept.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventActionNotAllowed
                message: Event action is not allowed
          description: Event action is not allowed
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventNotFound
                message: The specified event not found
          description: The specified event not found
      security:
        - header: []
  /api/v1/events/{eventId}/attendees:
    get:
      summary: Get private event attendees
      description: >-
        Returns the list of attendees for a private event along with their
        response statuses (accepted, tentative, rejected, pending).
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Show no more than the given number of attendees
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: An offset to show attendees starting from
          required: false
          name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EventAttendee'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventNotFound
                message: The specified event not found
          description: The specified event not found
      security:
        - header: []
  /api/v1/events/{eventId}/attendees/{userId}:
    delete:
      summary: Remove user from private event
      description: >-
        Revokes a user's invitation or removes them from a private event. Only
        the event organizer can remove attendees.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                EventNotFound:
                  description: The specified event not found
                  value:
                    errorCode: EventNotFound
                    message: The specified event not found
                UserNotFound:
                  description: User not found
                  value:
                    errorCode: UserNotFound
                    message: User not found
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventNotJoined
                message: The event has not been joined
          description: The event has not been joined
      security:
        - header: []
    post:
      summary: Invite user to private event
      description: >-
        Sends an invitation to a specific user for a private event. Only the
        event organizer can invite attendees.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                EventNotFound:
                  description: The specified event not found
                  value:
                    errorCode: EventNotFound
                    message: The specified event not found
                UserNotFound:
                  description: User not found
                  value:
                    errorCode: UserNotFound
                    message: User not found
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventAlreadyJoined
                message: The event has already been joined
          description: The event has already been joined
      security:
        - header: []
  /api/v1/events/{eventId}/cancel:
    post:
      summary: Cancel a scheduled event
      description: >-
        Cancels a scheduled event, notifying all attendees. The event remains
        visible but marked as cancelled. Only the event organizer can cancel.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventNotFound
                message: The specified event not found
          description: The specified event not found
      security:
        - header: []
  /api/v1/events/{eventId}/interested:
    post:
      summary: Express interest in an event
      description: >-
        Marks the authenticated user as interested in a public event. Cannot be
        used for private events. Returns updated event statistics.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventStats'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventNotFound
                message: The specified event not found
          description: The specified event not found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventAlreadyInterested
                message: The interest in event has been already shown
          description: The interest in event has been already shown
      security:
        - header: []
  /api/v1/events/{eventId}/join:
    post:
      summary: Join a public event
      description: >-
        Confirms attendance for a public event. Cannot be used for private
        events which require invitations. Returns updated event statistics.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventStats'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventNotFound
                message: The specified event not found
          description: The specified event not found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventAlreadyJoined
                message: The event has already been joined
          description: The event has already been joined
      security:
        - header: []
  /api/v1/events/{eventId}/joinOrInterested:
    delete:
      summary: Leave or revoke interest in event
      description: >-
        Removes the authenticated user's interest or participation in a public
        event. Cannot be used for private events. Returns updated event
        statistics.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventStats'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventNotFound
                message: The specified event not found
          description: The specified event not found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventNotJoinedNorInterestedIn
                message: The event has not been joined nor interested in
          description: The event has not been joined nor interested in
      security:
        - header: []
  /api/v1/events/{eventId}/maybe:
    post:
      summary: Tentatively accept private event
      description: >-
        Responds 'maybe' to a private event invitation, indicating tentative
        attendance. Only invited users can respond.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventActionNotAllowed
                message: Event action is not allowed
          description: Event action is not allowed
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventNotFound
                message: The specified event not found
          description: The specified event not found
      security:
        - header: []
  /api/v1/events/{eventId}/mutual:
    get:
      summary: Get mutual event attendees
      description: >-
        Returns a list of users who are both attending the specified public
        event and are followed by the authenticated user.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Show no more than the given number of items
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: An offset to show items starting from
          required: false
          name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/events/{eventId}/reject:
    post:
      summary: Reject private event invitation
      description: >-
        Declines an invitation to a private event. Only invited users can reject
        invitations.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventActionNotAllowed
                message: Event action is not allowed
          description: Event action is not allowed
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventNotFound
                message: The specified event not found
          description: The specified event not found
      security:
        - header: []
  /api/v1/events/{eventId}/translate:
    post:
      summary: Translate event content
      description: >-
        Translates event title and description to the specified language.
        Translation is cached for future requests.
      tags:
        - Events
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: lang
          in: query
          schema:
            $ref: '#/components/schemas/Language'
          required: true
      responses:
        '200':
          description: Event translation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventTranslation'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventNotFound
                message: The specified event not found
          description: The specified event not found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: EventAlreadyTranslated
                message: The event has already been translated
          description: The event has already been translated
      security:
        - header: []
  /api/v1/fasp/clear:
    post:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Clear
      tags:
        - Fasp Resource
      security: []
      description: 'RBAC: requires Federation.Manage'
  /api/v1/fasp/debug/v0/callback/callbacks:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: List
      tags:
        - Debug Resource
      security: []
  /api/v1/fasp/debug/v0/callback/callbacks/{id}:
    delete:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            format: int64
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Destroy
      tags:
        - Debug Resource
      security: []
  /api/v1/fasp/registration:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegistrationRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
      summary: Registration
      tags:
        - Fasp Resource
      security: []
      description: 'RBAC: requires Federation.Manage'
  /api/v1/fasp/{providerId}/capabilities:
    post:
      parameters:
        - name: providerId
          in: path
          required: true
          schema:
            format: int64
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Capability'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
      summary: Capabilities
      tags:
        - Fasp Resource
      security: []
      description: 'RBAC: requires Federation.Manage'
  /api/v1/fasp/{providerId}/debug-call:
    post:
      parameters:
        - name: providerId
          in: path
          required: true
          schema:
            format: int64
            type: integer
      requestBody:
        content:
          text/plain:
            schema:
              type: string
              nullable: true
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Debug Call
      tags:
        - Fasp Resource
      security: []
      description: 'RBAC: requires Federation.Manage'
  /api/v1/fasp/{providerId}/registration-finish:
    get:
      parameters:
        - name: providerId
          in: path
          required: true
          schema:
            format: int64
            type: integer
      responses:
        '200':
          description: OK
          content:
            text/html: {}
      summary: Registration Finish Page
      tags:
        - Fasp Resource
      security: []
      description: 'RBAC: requires Federation.Manage'
    post:
      parameters:
        - name: providerId
          in: path
          required: true
          schema:
            format: int64
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Registration Finish
      tags:
        - Fasp Resource
      security: []
      description: 'RBAC: requires Federation.Manage'
  /api/v1/fasp/{providerId}/request_backfill:
    post:
      parameters:
        - name: providerId
          in: path
          required: true
          schema:
            format: int64
            type: integer
        - name: category
          in: query
          schema:
            $ref: '#/components/schemas/Category1'
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Request Backfill
      tags:
        - Fasp Resource
      security: []
      description: 'RBAC: requires Federation.Manage'
  /api/v1/geo:
    get:
      summary: Get address from coordinates
      description: >-
        Performs reverse geocoding to convert latitude and longitude coordinates
        into a human-readable address. Requires authentication.
      tags:
        - Geo
      parameters:
        - description: Latitude coordinate in decimal degrees
          example: 40.7128
          required: true
          name: latitude
          in: query
          schema:
            format: double
            type: number
        - description: Longitude coordinate in decimal degrees
          example: -74.006
          required: true
          name: longitude
          in: query
          schema:
            format: double
            type: number
      responses:
        '200':
          description: >-
            The formatted address string corresponding to the provided
            coordinates
          content:
            text/plain:
              schema:
                type: string
                example: 123 Main Street, City, State, Country
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GeoCodingError
                message: An error occurred while geocoding the address
          description: An error occurred while geocoding the address
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/groups:
    get:
      summary: Get current user's group memberships
      description: >-
        Retrieves all groups that the currently authenticated user is a member
        of. Returns both public and private groups since the user is requesting
        their own memberships. Returns full Group objects with complete group
        details. Results are paginated. This is a convenience endpoint
        equivalent to calling /groups/member/{userId}/groups with your own user
        ID.
      tags:
        - Group Members
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of groups the current user is a member of
          content:
            application/json:
              schema:
                description: Array of Group objects for all groups the user belongs to
                type: array
                items:
                  $ref: '#/components/schemas/Group'
      security:
        - header: []
    post:
      summary: Create a new group
      description: >-
        Creates a new group owned by the currently authenticated user. The user
        becomes the group owner with full administrative privileges. The group
        name must be unique across the platform. A forum is automatically
        created for the group with default categories.
      tags:
        - Groups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupCreate'
        required: true
      responses:
        '200':
          description: Successfully created the new group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security:
        - header: []
  /api/v1/groups/account:
    get:
      summary: Get groups owned by current user
      description: >-
        Retrieves all groups that were created by the currently authenticated
        user account. This returns groups where the user is the
        owner/administrator, not just a member. A single user account can own
        and manage multiple groups. Returns full Group objects with complete
        group details including private groups owned by the user. Results are
        paginated.
      tags:
        - Group Members
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of groups owned by the current user
          content:
            application/json:
              schema:
                description: Array of Group objects for groups owned by the current user
                type: array
                items:
                  $ref: '#/components/schemas/Group'
      security:
        - header: []
  /api/v1/groups/apps:
    get:
      summary: List all group applications
      description: >-
        Returns a list of all applications available at the group entry point.
        These applications can be installed by any group. Requires
        authentication and appropriate permissions.
      tags:
        - Group Applications
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Application'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/groups/member/{userId}:
    get:
      summary: Get group memberships for a specific user
      description: >-
        Retrieves all group memberships for the specified user. Privacy rules
        apply: requesting your own memberships returns all groups (public and
        private), while requesting another user's memberships returns only their
        public group memberships. Results are paginated.
      tags:
        - Group Members
      parameters:
        - description: The unique identifier of the user whose memberships to retrieve
          example: us_01hz1f0kw36f82k9s4nzpc4s92n
          required: true
          name: userId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of group memberships for the user
          content:
            application/json:
              schema:
                description: Array of GroupMember objects containing membership details
                type: array
                items:
                  $ref: '#/components/schemas/GroupMember'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security:
        - header: []
  /api/v1/groups/member/{userId}/groups:
    get:
      summary: Get groups that a user is a member of
      description: >-
        Retrieves all groups where the specified user is a member. Privacy rules
        apply: requesting your own groups returns all groups (public and
        private), while requesting another user's groups returns only their
        public group memberships. Returns full Group objects rather than
        membership records. Results are paginated.
      tags:
        - Group Members
      parameters:
        - description: The unique identifier of the user whose groups to retrieve
          example: us_01hz1f0kw36f82k9s4nzpc4s92n
          required: true
          name: userId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of groups the user is a member of
          content:
            application/json:
              schema:
                description: Array of Group objects with full group details
                type: array
                items:
                  $ref: '#/components/schemas/Group'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security:
        - header: []
  /api/v1/groups/my-groups:
    get:
      summary: Get all user's groups with comprehensive sorting
      description: |2-

                    Returns user's groups in order:
                    1) pinned by pin number,
                    2) owned unpinned by creation date,
                    3) member unpinned by creation date
                
      tags:
        - Groups
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of user's groups with sorting information
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserGroupSummary'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security:
        - header: []
  /api/v1/groups/name/{groupname}:
    get:
      summary: Get group by name
      description: >-
        Retrieves a group using its unique name (slug). The group name is
        case-insensitive and must follow username validation rules
        (alphanumeric, underscores, hyphens). This is useful for human-readable
        URLs.
      tags:
        - Groups
      parameters:
        - description: The unique group name (slug)
          example: wine-lovers
          required: true
          name: groupname
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Group details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security: []
  /api/v1/groups/namecheck/{groupname}:
    get:
      summary: Check if group name is already in use
      description: >-
        Used for inline validation during group creation. Checks all local
        groups regardless of privacy settings. Returns a result object
        indicating whether the username is taken. Publicly accessible to allow
        group name validation during signup.
      tags:
        - Groups
      parameters:
        - description: The group name (slug) to check for availability
          example: wine-lovers
          required: true
          name: groupname
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Username availability check result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupnameCheck'
      security: []
  /api/v1/groups/pinned:
    get:
      summary: Get user's pinned groups
      description: Retrieve all groups pinned by the current user, ordered by pin number
      tags:
        - Groups
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of pinned groups
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GroupPin'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security:
        - header: []
  /api/v1/groups/search:
    get:
      summary: Search groups by name
      description: >-
        Searches for groups whose names contain the specified substring. The
        search is case-insensitive. If no substring is provided or it's empty,
        returns all visible groups. Results respect settings - only returns if
        group is public && visible or user is a member. Results are paginated.
      tags:
        - Groups
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Substring to search for in group names. Case-insensitive partial
            match.
          example: tech
          required: false
          name: substring
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of matching groups
          content:
            application/json:
              schema:
                description: Array of Group objects matching the search criteria
                type: array
                items:
                  $ref: '#/components/schemas/Group'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/groups/users/{userId}/mutual:
    get:
      summary: Get mutual groups with another user
      description: >-
        Retrieves groups that both the current user and the specified user are
        members of. Only returns groups where both users have active memberships
        (MEMBER status). Useful for finding common communities and shared
        interests between users.
      tags:
        - Groups
      parameters:
        - description: The unique identifier of the user to find mutual groups with
          example: us_01hz1f0kw36f82k9s4nzpc4s92n
          required: true
          name: userId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: List of groups both users belong to
          content:
            application/json:
              schema:
                description: Array of Group objects representing mutual memberships
                type: array
                items:
                  $ref: '#/components/schemas/Group'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/groups/{groupId}:
    put:
      summary: Update group information
      description: >-
        Updates the group's basic information including name, display name,
        description, and privacy settings. Requires GroupData.Manage permission.
        The group owner and administrators can perform this operation. Changes
        to privacy settings may affect member access and visibility.


        RBAC: requires GroupData.Manage
      tags:
        - Groups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupUpdate'
        required: true
      responses:
        '200':
          description: Successfully updated the group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ValidationError
                message: Invalid parameters
          description: Invalid parameters
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ResourceNotFound:
                  description: The requested resource not found
                  value:
                    errorCode: ResourceNotFound
                    message: The requested resource not found
                GroupNotFound:
                  description: Group not found
                  value:
                    errorCode: GroupNotFound
                    message: Group not found
          description: Not Found
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
    get:
      summary: Get group by ID
      description: >-
        Retrieves detailed information about a specific group. Returns full
        group data including metadata, settings, and upload references. Hidden
        groups return 404 for non-members to maintain privacy.
      tags:
        - Groups
      responses:
        '200':
          description: Group details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupContextIsEmpty
                message: Group context is not present
          description: Group context is not present
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ResourceNotFound:
                  description: The requested resource not found
                  value:
                    errorCode: ResourceNotFound
                    message: The requested resource not found
                GroupNotFound:
                  description: Group not found
                  value:
                    errorCode: GroupNotFound
                    message: Group not found
          description: Not Found
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
    delete:
      summary: Delete a group
      description: >-
        Permanently deletes a group and all associated data including
        memberships, roles, and forum content. This operation is irreversible.


        RBAC: requires Group.Delete
      tags:
        - Groups
      responses:
        '200':
          description: Group successfully deleted
          content:
            application/json:
              schema:
                type: boolean
                example: true
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ResourceNotFound:
                  description: The requested resource not found
                  value:
                    errorCode: ResourceNotFound
                    message: The requested resource not found
                GroupNotFound:
                  description: Group not found
                  value:
                    errorCode: GroupNotFound
                    message: Group not found
          description: Not Found
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/ai-agents/assignments:
    get:
      summary: List group AI agent assignments
      tags:
        - AI Agents
      parameters:
        - name: resourceId
          in: query
          schema:
            type: string
            nullable: true
        - name: type
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/AIAgentAssignmentType'
            nullable: true
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Assignments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AIAgentAssignment'
      security: []
      description: |-
        RBAC:
        - requires ANY of GroupAIAgents.Read, GroupAIAgents.Manage
    delete:
      summary: Delete an AI agent assignment
      tags:
        - AI Agents
      parameters:
        - name: assignmentId
          in: query
          schema:
            $ref: '#/components/schemas/TypeId'
          required: true
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      security: []
      description: 'RBAC: requires GroupAIAgents.Manage'
    post:
      summary: Create a group AI agent assignment
      tags:
        - AI Agents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AIAgentAssignmentCreate'
        required: true
      responses:
        '200':
          description: Created assignment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIAgentAssignment'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserIsNotBot
                message: The user is not a bot
          description: The user is not a bot
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: Forbidden
                message: No access to the resource
          description: No access to the resource
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupNotFound
                message: Group not found
          description: Group not found
      security: []
      description: 'RBAC: requires GroupAIAgents.Manage'
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/apps:
    get:
      summary: List applications for a specific group
      description: >-
        Returns a list of applications available to the specified group. Only
        group members can view the group's applications.
      tags:
        - Group Applications
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Application'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/apps/{appId}:
    delete:
      summary: Remove application from group
      description: Removes an application from the specified group's application list.
      tags:
        - Group Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ConstraintViolation
                message: A request parameter constraint was violated
          description: A request parameter constraint was violated
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppNotFound
                message: Application not found
          description: Application not found
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppUpdateError
                message: Failed to update the application
          description: Failed to update the application
      security: []
    put:
      summary: Add application to group
      description: >-
        Adds an application to the specified group's application list, making it
        available for group members.
      tags:
        - Group Applications
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Returns app
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ConstraintViolation
                message: A request parameter constraint was violated
          description: A request parameter constraint was violated
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppNotFound
                message: Application not found
          description: Application not found
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AppUpdateError
                message: Failed to update the application
          description: Failed to update the application
      security: []
  /api/v1/groups/{groupId}/branding:
    put:
      summary: Update group branding
      description: >-
        Updates the visual branding elements of a group including color theme,
        banner image, and avatar. Color must be in HEX format. Banner and avatar
        are references to previously uploaded media. Setting banner or avatar to
        null removes them. Requires group ownership or admin privileges.


        RBAC: requires GroupSettings.Manage
      tags:
        - Groups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupBrandingUpdate'
        required: true
      responses:
        '200':
          description: Successfully updated group branding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ValidationError
                message: Invalid parameters
          description: Invalid parameters
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ResourceNotFound:
                  description: The requested resource not found
                  value:
                    errorCode: ResourceNotFound
                    message: The requested resource not found
                GroupNotFound:
                  description: Group not found
                  value:
                    errorCode: GroupNotFound
                    message: Group not found
          description: Not Found
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/categories:
    get:
      summary: List all categories in a forum
      description: >-
        Returns a paginated list of all categories within the specified forum.
        Categories organize forum discussions into topics.
      tags:
        - Categories
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Category'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
    post:
      summary: Create a new forum category
      description: >-
        Creates a new category within a forum. Categories organize forum
        discussions into topics.


        RBAC: requires GroupForum.Manage
      tags:
        - Categories
      requestBody:
        description: >-
          Category creation details including name, display name, and optional
          metadata
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryCreate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/categories/name/{categoryName}:
    get:
      summary: Get forum category by name
      description: >-
        Retrieves a specific category within a forum by its unique name
        identifier.
      tags:
        - Categories
      parameters:
        - name: categoryName
          in: path
          required: true
          schema:
            type: string
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: CategoryNotFound
                message: The specified category not found
          description: The specified category not found
      security: []
  /api/v1/groups/{groupId}/categories/namecheck/{categoryName}:
    get:
      summary: Check if category name is already in use
      description: >-
        Validates category name availability within the forum during creation.
        Returns whether the name is already taken within the group's forum.
        Requires GroupForum.Manage permission.


        RBAC: requires GroupForum.Manage
      tags:
        - Categories
      parameters:
        - description: >-
            The category name (slug) to check for availability. Must be
            lowercase alphanumeric with hyphens (not
            leading/trailing/consecutive).
          example: general-discussion
          required: true
          name: categoryName
          in: path
          schema:
            pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
            type: string
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Category name availability check result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryNameCheck'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ResourceNotFound:
                  description: The requested resource not found
                  value:
                    errorCode: ResourceNotFound
                    message: The requested resource not found
                GroupNotFound:
                  description: Group not found
                  value:
                    errorCode: GroupNotFound
                    message: Group not found
          description: Not Found
      security: []
  /api/v1/groups/{groupId}/categories/{categoryId}:
    put:
      summary: Update an existing category
      description: >-
        Updates category properties including name, description, allowed tags,
        and metadata. Only authenticated users with appropriate permissions can
        update categories.


        RBAC: requires GroupForum.Manage
      tags:
        - Categories
      parameters:
        - description: The unique identifier of the category to update
          in: path
          required: true
          name: categoryId
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        description: Category update details including optional fields to modify
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryUpdate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: CategoryNotFound
                message: The specified category not found
          description: The specified category not found
      security: []
    get:
      summary: Get category details by ID
      description: >-
        Retrieves detailed information about a specific category including its
        name, description, allowed tags, and metadata. Public access allowed.
      tags:
        - Categories
      parameters:
        - description: The unique identifier of the category to retrieve
          example: cat_01hz1f0kw36f82k9s4nzpc4s92n
          in: path
          required: true
          name: categoryId
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: CategoryNotFound
                message: The specified category not found
          description: The specified category not found
      security: []
    delete:
      summary: Delete a forum category
      description: >-
        Permanently deletes a category from a forum. Cannot delete the last
        category in a forum - at least one category must remain. Requires
        authentication and appropriate permissions.


        RBAC: requires GroupForum.Manage
      tags:
        - Categories
      parameters:
        - description: The unique identifier of the category to delete
          in: path
          required: true
          name: categoryId
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ClientError
                message: Invalid request from client
          description: Invalid request from client
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: CategoryNotFound
                message: The specified category not found
          description: The specified category not found
      security: []
  /api/v1/groups/{groupId}/channels:
    get:
      summary: List all group channels
      description: >-
        Retrieves a complete list of all channels within the specified group.
        Requires group membership to access. Returns both public and private
        channels visible to the authenticated user. The response includes
        channel metadata such as privacy settings, default status, and whether
        each channel is designated as the main channel. Channels are returned in
        creation order.


        RBAC: requires GroupChannels.Read
      tags:
        - Group Channels
      responses:
        '200':
          description: Complete list of group channels successfully retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
    post:
      summary: Create a new group channel
      description: >-
        Creates a new channel within the specified group. Requires group
        administrator privileges. The channel's privacy is constrained by the
        parent group's privacy settings (private groups can only have private
        channels). The first channel created is automatically designated as both
        main and default. Channels can have both scoped usernames
        (group-specific) and optional global usernames (platform-wide). Note:
        Avatar and header images must be set via the update endpoint after
        channel creation.


        RBAC: requires GroupChannels.Manage
      tags:
        - Group Channels
      requestBody:
        content:
          application/json:
            schema:
              description: >-
                Channel configuration including username, display name, privacy,
                and role settings
              allOf:
                - $ref: '#/components/schemas/GroupChannelCreateRequest'
        required: true
      responses:
        '200':
          description: Channel created successfully with all configured properties
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFull'
        '400':
          description: Bad Request
      security: []
      parameters:
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/channels/default:
    get:
      summary: List default channels
      description: >-
        Retrieves all channels designated as default for the specified group.
        Default channels are automatically followed by new members upon joining.
        Requires group membership to access. Returns an empty array if no
        default channels are configured. The response includes full channel
        information including privacy settings and follow status.


        RBAC: requires GroupChannels.Read
      tags:
        - Group Channels
      responses:
        '200':
          description: List of default channels successfully retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/channels/lookup:
    get:
      summary: Get group channel by scoped username
      description: >-
        Retrieves a channel using its group-scoped username (slug). Useful for
        accessing channels without global usernames. Private channels and
        channels inside private groups require membership and otherwise return
        404.
      tags:
        - Group Channels
      parameters:
        - description: >-
            If true return also summary, stats, header and fields. Default
            false.
          required: false
          name: full
          in: query
          schema:
            type: boolean
            nullable: true
        - name: username
          in: query
          schema:
            description: Channel slug unique within the group (e.g. "news").
            pattern: \S
            type: string
          required: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Channel information successfully retrieved
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/User'
                  - $ref: '#/components/schemas/UserFull'
      security: []
  /api/v1/groups/{groupId}/channels/main:
    get:
      summary: Retrieve main channel
      description: >-
        Retrieves the designated main channel for the specified group. Access
        control is based on both group and channel privacy settings. Public
        groups with public main channels are accessible to everyone. Private
        groups or private channels require group membership. Returns 404 if no
        main channel is designated or if access is denied due to privacy
        settings.
      tags:
        - Group Channels
      responses:
        '200':
          description: Main channel information successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFull'
      security: []
      parameters:
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/channels/namecheck/{channelUsername}:
    get:
      summary: Check if channel username is already in use
      description: >-
        Used for inline validation during channel creation. Scoped to the group.
        Returns a result object indicating whether the username is taken within
        the specified group.


        RBAC: requires GroupChannels.Manage
      tags:
        - Group Channels
      parameters:
        - description: The channel username (slug) to check for availability
          required: true
          name: channelUsername
          in: path
          schema:
            type: string
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Username availability check result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupnameCheck'
      security: []
  /api/v1/groups/{groupId}/channels/public:
    get:
      summary: List public channels
      description: >-
        Retrieves all public channels from a public group. This endpoint is
        accessible to everyone, including non-members and unauthenticated users,
        but only works for public groups. Private groups will return an error
        regardless of their channels' privacy settings. Useful for discovery and
        browsing group content before joining. Channels with global usernames
        are included with their platform-wide identifiers.
      tags:
        - Group Channels
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/channels/{channelId}:
    put:
      summary: Update an existing group channel
      description: >-
        Modifies properties of an existing channel. Requires group administrator
        privileges. Only included fields are updated; null fields preserve
        existing values. Privacy changes are constrained by the parent group's
        privacy (cannot make a channel public in a private group). Changes to
        default status affect auto-follow behavior for new members.


        RBAC: requires GroupChannels.Manage
      tags:
        - Group Channels
      parameters:
        - name: channelId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              description: Fields to modify. Omit fields to preserve current values.
              allOf:
                - $ref: '#/components/schemas/GroupChannelUpdateRequest'
        required: true
      responses:
        '200':
          description: Channel properties updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFull'
        '400':
          description: Bad Request
      security: []
    get:
      summary: Get group channel by id
      description: >-
        Retrieves a channel within the current group by its identifier. Access
        to private channels (or channels in private groups) is restricted to
        group members; outsiders receive a 404.
      tags:
        - Group Channels
      parameters:
        - name: channelId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            If true return also summary, stats, header and fields. Default
            false.
          name: full
          in: query
          schema:
            type: boolean
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Channel information successfully retrieved
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/User'
                  - $ref: '#/components/schemas/UserFull'
      security: []
    delete:
      summary: Delete a group channel
      description: >-
        Removes the specified channel from the group. Requires group
        administrator privileges. The channel is marked as deleted immediately
        and background workers handle cleanup of posts, media, and follower
        relationships.


        RBAC: requires GroupChannels.Manage
      tags:
        - Group Channels
      parameters:
        - name: channelId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      security: []
  /api/v1/groups/{groupId}/channels/{channelId}/default:
    put:
      summary: Update channel default status
      description: >-
        Toggles whether a channel is designated as a default channel. Requires
        group administrator privileges. Default channels are automatically
        followed by new group members upon joining. Multiple channels can be
        marked as default. This setting helps onboard new members by ensuring
        they receive content from essential channels immediately.


        RBAC: requires GroupChannels.Manage
      tags:
        - Group Channels
      parameters:
        - name: channelId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: isDefault
          in: query
          schema:
            description: >-
              Whether to mark the channel as default (true) or remove default
              status (false)
            default: true
            type: boolean
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Default channel status successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFull'
      security: []
  /api/v1/groups/{groupId}/channels/{channelId}/main:
    put:
      summary: Designate channel as main
      description: >-
        Sets the specified channel as the main channel for the group. Requires
        group administrator privileges. Only one channel can be designated as
        main per group. The main channel serves as the primary communication
        channel and is prominently displayed in group interfaces. Any existing
        main channel designation is automatically removed.


        RBAC: requires GroupChannels.Manage
      tags:
        - Group Channels
      parameters:
        - name: channelId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: >-
            Channel successfully designated as main, previous main channel
            designation removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFull'
      security: []
  /api/v1/groups/{groupId}/channels/{channelId}/username:
    put:
      summary: Assign or update global username
      description: >-
        Assigns, updates, or removes a global username for a public channel.
        Requires group administrator privileges. Global usernames provide
        platform-wide discovery and must be unique across the entire system.
        Only public channels in public groups can have global usernames. Setting
        the username to null removes any existing global username assignment.


        RBAC: requires GroupChannels.Manage
      tags:
        - Group Channels
      parameters:
        - name: channelId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              description: global username to assign or null to remove
              allOf:
                - $ref: '#/components/schemas/AssignGlobalUsernameRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFull'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                GroupContextIsEmpty:
                  description: Group context is not present
                  value:
                    errorCode: GroupContextIsEmpty
                    message: Group context is not present
                InvalidActorType:
                  description: Invalid actor type for a user or channel
                  value:
                    errorCode: InvalidActorType
                    message: Invalid actor type for a user or channel
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: Forbidden
                message: No access to the resource
          description: No access to the resource
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                GroupNotFound:
                  description: Group not found
                  value:
                    errorCode: GroupNotFound
                    message: Group not found
                UserNotFound:
                  description: User not found
                  value:
                    errorCode: UserNotFound
                    message: User not found
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNameExists
                message: The username is already in use
          description: The username is already in use
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ServerError
                message: An unexpected server error occurred
          description: An unexpected server error occurred
      security: []
  /api/v1/groups/{groupId}/forum:
    put:
      summary: Update forum settings
      description: >-
        Updates forum configuration including visibility, policy, and metadata.
        Requires authentication and appropriate permissions.


        RBAC: requires GroupForum.Manage
      tags:
        - Forums
      requestBody:
        description: Forum update details including visibility, policy, and metadata
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForumUpdate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forum'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ForumNotFound
                message: The specified forum not found
          description: The specified forum not found
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
    get:
      summary: Get group's forum
      description: >-
        Retrieves detailed information about a specific forum including its
        visibility settings, policy, and metadata. If the group doesn't have a
        forum, automatically creates a new forum with default categories.
        Visible according to Group settings.
      tags:
        - Forums
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forum'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ForumNotFound
                message: The specified forum not found
          description: The specified forum not found
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
    delete:
      summary: Delete a forum
      description: >-
        Permanently deletes a forum and all its associated data. This action is
        irreversible. Requires authentication and owner permissions.


        RBAC: requires GroupForum.Manage
      tags:
        - Forums
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forum'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ForumNotFound
                message: The specified forum not found
          description: The specified forum not found
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/forum/hard:
    delete:
      summary: Permanently delete a forum
      description: >-
        Permanently deletes a forum and all its associated categories. Requires
        authentication and forum management permissions. Administrative
        operation.


        RBAC: requires GroupData.Manage
      tags:
        - Forums
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forum'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ForumNotFound
                message: The specified forum not found
          description: The specified forum not found
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/forum/stats:
    get:
      summary: Get forum statistics
      description: Returns statistics for the forum including number of categories and tags
      tags:
        - Forums
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForumStats'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ForumNotFound
                message: The specified forum not found
          description: The specified forum not found
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/forum/tags:
    get:
      summary: List all forum tags
      description: >-
        Returns a paginated list of all tags used within the specified forum,
        sorted by usage frequency.
      tags:
        - Forums
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tag'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/groups/{groupId}/forum/tags/search:
    get:
      summary: Search forum tags for autocompletion
      description: >-
        Searches for tags within a forum by prefix, primarily used for tag
        autocompletion in user interfaces. Returns matching tags sorted by usage
        frequency.
      tags:
        - Forums
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Search query
          required: false
          name: q
          in: query
          schema:
            type: string
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tag'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/groups/{groupId}/join:
    post:
      summary: Join a group
      description: |2-

                    Request to join a group. The behavior depends on the group's join mode:
                    OPEN groups accept members immediately with MEMBER role, APPROVAL groups create a PENDING membership
                    requiring admin approval, and INVITE_ONLY groups require an invitation. Groups may also have
                    entry questions that require a valid answerToken from completing the group's questionnaire.
                    Users cannot join a group they're already a member of.
                
      tags:
        - Groups
      parameters:
        - description: |2-

                            Token received after successfully answering group entry questions.
                            Required only for groups with entry questions when joinQuestions.show is true.
                        
          example: tk_abc123def456
          required: false
          name: answerToken
          in: query
          schema:
            type: string
            nullable: true
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: >-
            Successfully joined the group (OPEN mode) or join request submitted
            (APPROVAL mode)
          content:
            application/json:
              schema:
                description: >-
                  The membership record: status=MEMBER for OPEN mode,
                  status=PENDING for APPROVAL mode
                required:
                  - groupName
                  - groupDisplayName
                  - userName
                  - userDisplayName
                  - groupId
                  - memberId
                  - status
                type: object
                properties:
                  groupName:
                    description: Group name
                    type: string
                  groupDisplayName:
                    description: Group display name
                    type: string
                  userName:
                    description: User name (username)
                    type: string
                  userDisplayName:
                    description: User display name
                    type: string
                  userDomain:
                    description: User domain (null for local users)
                    type: string
                    nullable: true
                  groupAvatar:
                    description: Group avatar upload object
                    type: object
                    allOf:
                      - $ref: '#/components/schemas/Upload'
                    nullable: true
                  userAvatar:
                    description: User avatar upload object
                    type: object
                    allOf:
                      - $ref: '#/components/schemas/Upload'
                    nullable: true
                  groupId:
                    description: Group ID
                    type: string
                    allOf:
                      - $ref: '#/components/schemas/TypeId'
                  memberId:
                    description: User who is a member of the group
                    type: string
                    allOf:
                      - $ref: '#/components/schemas/TypeId'
                  role:
                    description: |2-

                                  The role identifier that determines the member's permissions within the group.
                                  Common roles include GROUP_VIEWER, GROUP_EDITOR, GROUP_ADMIN
                              
                    type: string
                    nullable: true
                  meta:
                    description: Additional metadata about this membership
                    type: object
                    allOf:
                      - $ref: '#/components/schemas/GroupMemberMeta'
                    nullable: true
                  status:
                    description: >-
                      Current status of the membership (INVITED, MEMBER, or
                      PENDING)
                    type: string
                    allOf:
                      - $ref: '#/components/schemas/GroupMemberStatus'
                  createdAt:
                    allOf:
                      - $ref: '#/components/schemas/Instant'
                    nullable: true
                  updatedAt:
                    allOf:
                      - $ref: '#/components/schemas/Instant'
                    nullable: true
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ClientError:
                  description: Invalid request from client
                  value:
                    errorCode: ClientError
                    message: Invalid request from client
                InvalidQuestion:
                  description: Invalid question provided
                  value:
                    errorCode: InvalidQuestion
                    message: Invalid question provided
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ResourceNotFound:
                  description: The requested resource not found
                  value:
                    errorCode: ResourceNotFound
                    message: The requested resource not found
                GroupNotFound:
                  description: Group not found
                  value:
                    errorCode: GroupNotFound
                    message: Group not found
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                GroupMembershipLimitExceeded:
                  description: Group has reached its maximum member limit
                  value:
                    errorCode: GroupMembershipLimitExceeded
                    message: Group has reached its maximum member limit
                GroupAlreadyMember:
                  description: User is already a member of this group
                  value:
                    errorCode: GroupAlreadyMember
                    message: User is already a member of this group
                GroupInviteOnlyMode:
                  description: This group is invite-only and requires an invitation to join
                  value:
                    errorCode: GroupInviteOnlyMode
                    message: >-
                      This group is invite-only and requires an invitation to
                      join
          description: Conflict
      security:
        - header: []
    delete:
      summary: Cancel group join request
      description: |2-

                    Cancel a join request for a group. This allows users to withdraw their request
                    to join a group that requires approval. Only the user who made
                    the original join request can cancel it.
                
      tags:
        - Groups
      responses:
        '200':
          description: Successfully canceled join request
          content:
            application/json:
              schema:
                description: Always returns true when join request is successfully canceled
                type: boolean
                example: true
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ResourceNotFound:
                  description: The requested resource not found
                  value:
                    errorCode: ResourceNotFound
                    message: The requested resource not found
                GroupNotFound:
                  description: Group not found
                  value:
                    errorCode: GroupNotFound
                    message: Group not found
          description: Not Found
      security:
        - header: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/join-requests:
    get:
      summary: List join requests for a group
      description: |2-

                    Get a list of join requests for a group with optional filtering by status, username, and date range.
                    Only group admins can access this endpoint

        RBAC: requires GroupMembers.Manage
      tags:
        - Groups
      parameters:
        - description: Filter by creation date (start), inclusive
          example: '2025-01-01'
          required: false
          name: createdFrom
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/LocalDate'
            nullable: true
        - description: Filter by creation date (end), inclusive
          example: '2025-12-31'
          required: false
          name: createdTo
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/LocalDate'
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: Filter requests by status. If omitted, returns all requests.
          required: false
          name: status
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/GroupJoinRequestStatus'
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Filter by username (case-insensitive exact match)
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: >-
                  Response with items array, grandTotal (unfiltered), and total
                  (filtered) counts
                required:
                  - requests
                  - grandTotal
                  - total
                type: object
                properties:
                  requests:
                    description: Array of group join request objects
                    type: array
                    items:
                      $ref: '#/components/schemas/GroupJoinRequest'
                  grandTotal:
                    format: int32
                    description: >-
                      Total number of join requests for the specified group (no
                      filters applied)
                    type: integer
                  total:
                    format: int32
                    description: Total number of join requests matching the applied filters
                    type: integer
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupNotFound
                message: Group not found
          description: Group not found
      security:
        - header: []
  /api/v1/groups/{groupId}/join-requests/{groupJoinRequestId}:
    delete:
      summary: Reject a join request
      description: |2-

                    Reject a user's join request for a group. This removes the request
                    without creating a membership. Only group admins can reject join requests.

        RBAC: requires GroupMembers.Manage
      tags:
        - Groups
      parameters:
        - description: The unique identifier of the join request to reject
          required: true
          name: groupJoinRequestId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Optional reason for rejecting the request
          required: false
          name: reason
          in: query
          schema:
            type: string
            nullable: true
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Successfully rejected join request
          content:
            application/json:
              schema:
                description: True if the request was successfully rejected
                type: boolean
                example: true
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ClientError
                message: Invalid request from client
          description: Invalid request from client
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
    put:
      summary: Approve a join request
      description: |2-

                    Approve a join request for a group. This converts the request
                    into an active group membership with MEMBER role. Only group admins can approve join requests.

        RBAC: requires GroupMembers.Manage
      tags:
        - Groups
      parameters:
        - description: The unique identifier of the join request to approve
          required: true
          name: groupJoinRequestId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Optional reason for approving the request
          required: false
          name: reason
          in: query
          schema:
            type: string
            nullable: true
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Successfully approved join request
          content:
            application/json:
              schema:
                description: >-
                  The approved membership record with MEMBER role and active
                  status
                required:
                  - groupName
                  - groupDisplayName
                  - userName
                  - userDisplayName
                  - groupId
                  - memberId
                  - status
                type: object
                properties:
                  groupName:
                    description: Group name
                    type: string
                  groupDisplayName:
                    description: Group display name
                    type: string
                  userName:
                    description: User name (username)
                    type: string
                  userDisplayName:
                    description: User display name
                    type: string
                  userDomain:
                    description: User domain (null for local users)
                    type: string
                    nullable: true
                  groupAvatar:
                    description: Group avatar upload object
                    type: object
                    allOf:
                      - $ref: '#/components/schemas/Upload'
                    nullable: true
                  userAvatar:
                    description: User avatar upload object
                    type: object
                    allOf:
                      - $ref: '#/components/schemas/Upload'
                    nullable: true
                  groupId:
                    description: Group ID
                    type: string
                    allOf:
                      - $ref: '#/components/schemas/TypeId'
                  memberId:
                    description: User who is a member of the group
                    type: string
                    allOf:
                      - $ref: '#/components/schemas/TypeId'
                  role:
                    description: |2-

                                  The role identifier that determines the member's permissions within the group.
                                  Common roles include GROUP_VIEWER, GROUP_EDITOR, GROUP_ADMIN
                              
                    type: string
                    nullable: true
                  meta:
                    description: Additional metadata about this membership
                    type: object
                    allOf:
                      - $ref: '#/components/schemas/GroupMemberMeta'
                    nullable: true
                  status:
                    description: >-
                      Current status of the membership (INVITED, MEMBER, or
                      PENDING)
                    type: string
                    allOf:
                      - $ref: '#/components/schemas/GroupMemberStatus'
                  createdAt:
                    allOf:
                      - $ref: '#/components/schemas/Instant'
                    nullable: true
                  updatedAt:
                    allOf:
                      - $ref: '#/components/schemas/Instant'
                    nullable: true
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ClientError
                message: Invalid request from client
          description: Invalid request from client
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/groups/{groupId}/member-settings:
    put:
      summary: Update member's personal settings for a group
      description: >-
        Updates one or more of the current member's personal settings within the
        specified group. Multiple settings can be updated in a single request.
        Complete setting objects must be provided - partial updates of
        individual settings are not supported. Members can only update their own
        settings and must be active members of the group. Changes take effect
        immediately.
      tags:
        - Group Member Settings
      requestBody:
        description: >-
          settings objects to be updated. complete objects must be provided -
          partial updates are not allowed.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupMemberSettings'
        required: true
      responses:
        '200':
          description: Update confirmation with count of successfully updated settings
          content:
            application/json:
              example:
                updated: 3
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                SettingsInvalidKeyProvided:
                  description: Unknown settings key(s) %s
                  value:
                    errorCode: SettingsInvalidKeyProvided
                    message: Unknown settings key(s) %s
                SettingsKeyNotProvided:
                  description: No settings keys were provided
                  value:
                    errorCode: SettingsKeyNotProvided
                    message: No settings keys were provided
                SettingsValuesNotProvided:
                  description: No settings values were provided
                  value:
                    errorCode: SettingsValuesNotProvided
                    message: No settings values were provided
                SettingsPartialUpdateNotAllowed:
                  description: 'Partial updates are not allowed: %s'
                  value:
                    errorCode: SettingsPartialUpdateNotAllowed
                    message: 'Partial updates are not allowed: %s'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsForbidden
                message: Access denied for settings
          description: Access denied for settings
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupNotFound
                message: Group not found
          description: Group not found
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsNotUpdated
                message: Failed to update settings
          description: Failed to update settings
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
    get:
      summary: Get member's personal settings for a group
      description: >-
        Retrieves the current member's personal settings within the specified
        group. Returns a JSON object with setting keys mapped to their values.
        Members can only access their own settings and must be active members of
        the group. Settings control member-specific preferences like
        notification preferences, display options, and personal configurations
        within the group context.
      tags:
        - Group Member Settings
      parameters:
        - description: >-
            Comma-separated list of setting keys to retrieve. Keys must be valid
            group member setting identifiers.


            Available keys are:


            ```group.member.display```


            ```group.member.preferences```
          name: keys
          required: true
          in: query
          schema:
            type: array
            items:
              type: string
          example: group.member.display,group.member.preferences
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/GroupMemberSettings'
          description: Response GroupMemberSettings
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                SettingsInvalidKeyProvided:
                  description: Unknown settings key(s) %s
                  value:
                    errorCode: SettingsInvalidKeyProvided
                    message: Unknown settings key(s) %s
                SettingsKeyNotProvided:
                  description: No settings keys were provided
                  value:
                    errorCode: SettingsKeyNotProvided
                    message: No settings keys were provided
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsForbidden
                message: Access denied for settings
          description: Access denied for settings
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupNotFound
                message: Group not found
          description: Group not found
      security: []
    delete:
      summary: Delete member's personal settings for a group
      description: >-
        Deletes one or more of the current member's personal settings within the
        specified group, reverting them to default values. Multiple settings can
        be deleted in a single request. Members can only delete their own
        settings and must be active members of the group. After deletion, the
        settings will use system or group defaults.
      tags:
        - Group Member Settings
      parameters:
        - description: >-
            Comma-separated list of setting keys to delete. Keys must be valid
            group member setting identifiers.


            Available keys are:


            ```group.member.display```


            ```group.member.preferences```
          name: keys
          required: true
          in: query
          schema:
            type: array
            items:
              type: string
          example: group.member.display,group.member.preferences
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Deletion confirmation with count of successfully deleted settings
          content:
            application/json:
              example:
                deleted: 3
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                SettingsKeyNotProvided:
                  description: No settings keys were provided
                  value:
                    errorCode: SettingsKeyNotProvided
                    message: No settings keys were provided
                SettingsInvalidKeyProvided:
                  description: Unknown settings key(s) %s
                  value:
                    errorCode: SettingsInvalidKeyProvided
                    message: Unknown settings key(s) %s
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsForbidden
                message: Access denied for settings
          description: Access denied for settings
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupNotFound
                message: Group not found
          description: Group not found
      security: []
  /api/v1/groups/{groupId}/members:
    get:
      summary: Get all members of a group
      description: |2-

                    Retrieves the list of all members in the specified group as GroupMember objects.
                    Public groups are accessible to all authenticated users, Private groups accessible to members only.
                    Supports sorting by join time, posts, or relationship to current user.
                    Supports role filtering and pagination.
                
      tags:
        - Group Members
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Sort order (case-insensitive)
          required: false
          name: order
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/SortOrder'
            nullable: true
        - description: Role filter (case-insensitive)
          required: false
          name: role
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/GroupMemberRoleFilter'
            nullable: true
        - description: Sort field (case-insensitive)
          required: false
          name: sort
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/GroupMembersSortBy'
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: List of group members with their membership details
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GroupMember'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupContextIsEmpty
                message: Group context is not present
          description: Group context is not present
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
                NotGroupMember:
                  description: The user must be a member of the group
                  value:
                    errorCode: NotGroupMember
                    message: The user must be a member of the group
                GroupMemberListNotPublic:
                  description: Group member list is not visible to non-members
                  value:
                    errorCode: GroupMemberListNotPublic
                    message: Group member list is not visible to non-members
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupNotFound
                message: Group not found
          description: Group not found
      security: []
    post:
      summary: Add a new member to a group
      description: >-
        Adds a user as a member of the specified group. For local groups, the
        membership is created immediately. For federated groups, an ActivityPub
        message is sent to the remote server. The requesting user must have
        GroupMembers.Manage permission for the target group. The groupId is
        provided in the URL path.


        RBAC: requires GroupMembers.Manage
      tags:
        - Group Members
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupMemberCreate'
        required: true
      responses:
        '200':
          description: Successfully added member to the group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMember'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ResourceNotFound:
                  description: The requested resource not found
                  value:
                    errorCode: ResourceNotFound
                    message: The requested resource not found
                GroupNotFound:
                  description: Group not found
                  value:
                    errorCode: GroupNotFound
                    message: Group not found
          description: Not Found
      security:
        - header: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/members/{memberId}:
    put:
      summary: Update an existing group member
      description: >-
        Updates the role, status, or metadata of an existing group member. For
        local groups, the update is applied immediately. For federated groups,
        an ActivityPub message is sent to the remote server to request the
        update. Requires GroupMembers.Manage permission for the target group.


        RBAC: requires GroupMembers.Manage
      tags:
        - Group Members
      parameters:
        - description: The unique identifier of the user whose membership is being updated
          example: us_01hz1f0kw36f82k9s4nzpc4s92n
          required: true
          name: memberId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupMemberUpdate'
        required: true
      responses:
        '200':
          description: Successfully updated the group member
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMember'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ResourceNotFound:
                  description: The requested resource not found
                  value:
                    errorCode: ResourceNotFound
                    message: The requested resource not found
                GroupNotFound:
                  description: Group not found
                  value:
                    errorCode: GroupNotFound
                    message: Group not found
          description: Not Found
      security: []
    delete:
      summary: Remove a member from a group
      description: >-
        Removes the specified user from the group. For local groups, the
        membership is deleted immediately. For federated groups, an ActivityPub
        message is sent to request removal. Requires GroupMembers.Manage
        permission. An optional reason can be provided for audit logging.


        RBAC: requires GroupMembers.Manage
      tags:
        - Group Members
      parameters:
        - description: The unique identifier of the user to remove from the group
          example: us_01hz1f0kw36f82k9s4nzpc4s92n
          required: true
          name: memberId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            Optional reason for removing the member. This will be recorded in
            the audit log for accountability and compliance purposes.
          example: Violation of community guidelines
          required: false
          name: reason
          in: query
          schema:
            type: string
            nullable: true
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Member successfully removed from the group
          content:
            application/json:
              schema:
                type: boolean
                example: true
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ResourceNotFound:
                  description: The requested resource not found
                  value:
                    errorCode: ResourceNotFound
                    message: The requested resource not found
                GroupNotFound:
                  description: Group not found
                  value:
                    errorCode: GroupNotFound
                    message: Group not found
          description: Not Found
      security: []
  /api/v1/groups/{groupId}/membership:
    delete:
      summary: Leave a group
      description: >-
        Removes the authenticated user from the group. User's posts/comments
        remain but permissions are revoked. Can rejoin later with fresh
        membership.
      tags:
        - Group Members
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: boolean
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupContextIsEmpty
                message: Group context is not present
          description: Group context is not present
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: CantRemoveLastAdmin
                message: Cannot remove the last remaining admin user
          description: Cannot remove the last remaining admin user
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
    get:
      summary: Get current user's membership in a group
      description: >-
        Returns the membership object for the authenticated user in the
        specified group. Works for all membership statuses including
        pending/invited members.
      tags:
        - Group Members
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMember'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupContextIsEmpty
                message: Group context is not present
          description: Group context is not present
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/pin:
    delete:
      summary: Unpin a group
      description: Remove pin from a group. User must be a member of the group.
      tags:
        - Groups
      responses:
        '200':
          description: Group successfully unpinned
          content:
            application/json:
              schema:
                type: boolean
                example: true
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                NotGroupMember:
                  description: The user must be a member of the group
                  value:
                    errorCode: NotGroupMember
                    message: The user must be a member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
    put:
      summary: Pin a group
      description: Pin a group with optional pin number. User must be a member of the group
      tags:
        - Groups
      parameters:
        - description: >-
            Pin order number. If not provided, next available number will be
            used
          example: 1
          name: pin
          required: false
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Group successfully pinned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupPin'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                NotGroupMember:
                  description: The user must be a member of the group
                  value:
                    errorCode: NotGroupMember
                    message: The user must be a member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/groups/{groupId}/questions:
    get:
      summary: Get all questions for a group
      description: >-
        Retrieves the complete list of questions that prospective members must
        answer when joining the group. Questions are returned in order based on
        their ordering value (lowest first). This endpoint is not accessible for
        groups with INVITE_ONLY join mode. Authentication is required to prevent
        question harvesting.
      tags:
        - Group Questions
      parameters:
        - description: The unique identifier of the group whose questions to retrieve
          example: gr_01hz1f0kw36f82k9s4nzpc4s92n
          required: true
          name: groupId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: List of group questions sorted by ordering
          content:
            application/json:
              schema:
                description: >-
                  Array of Question objects with text, type, choices, and
                  ordering
                type: array
                items:
                  $ref: '#/components/schemas/Question'
      security:
        - header: []
    post:
      summary: Create a new group question
      description: >-
        Adds a new question that prospective members must answer when joining
        the group. Requires GroupQuestions.Manage permission. Questions can be
        of type TEXT (free-form answer), SINGLE_CHOICE (one option), or
        MULTIPLE_CHOICE (multiple options). For choice questions, provide the
        available options in the choices array. The creation is tracked in the
        audit log.


        RBAC: requires GroupQuestions.Manage
      tags:
        - Group Questions
      parameters:
        - description: The unique identifier of the group to add the question to
          example: gr_01hz1f0kw36f82k9s4nzpc4s92n
          required: true
          name: groupId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuestionCreate'
        required: true
      responses:
        '200':
          description: Successfully created the new question
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Question'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ValidationError
                message: Invalid parameters
          description: Invalid parameters
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/groups/{groupId}/questions/answers:
    post:
      summary: Submit answers to group entry questions
      description: >-
        Submits answers to all required group questions as part of the join
        process. Returns a token that must be provided when calling the join
        endpoint. The group must have questions enabled (joinQuestions.show =
        true) and the user must not already be a member. Answers are validated
        against the current questions and stored for review by group
        administrators. The token expires after a configured period.
      tags:
        - Group Questions
      parameters:
        - description: The unique identifier of the group to submit answers for
          example: gr_01hz1f0kw36f82k9s4nzpc4s92n
          required: true
          name: groupId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuestionAnswerCreate'
        required: true
      responses:
        '200':
          description: Answer token generated successfully
          content:
            application/json:
              schema:
                description: Response containing the answer token and submission timestamp
                required:
                  - answerToken
                  - submittedAt
                type: object
                properties:
                  answerToken:
                    description: >-
                      Authentication token to be used with the group join
                      endpoint. Has a limited validity period.
                    type: string
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                  submittedAt:
                    description: >-
                      ISO 8601 timestamp indicating when the answers were
                      submitted
                    type: string
                    allOf:
                      - $ref: '#/components/schemas/Instant'
                    example: '2024-01-15T10:30:00Z'
        '400':
          description: Bad Request
      security:
        - header: []
  /api/v1/groups/{groupId}/questions/{questionId}:
    put:
      summary: Update an existing group question
      description: >-
        Modifies an existing question's text, type, choices, or ordering.
        Requires GroupQuestions.Manage permission. When changing question type,
        ensure the choices array is appropriate (empty for TEXT, populated for
        SINGLE_CHOICE/MULTIPLE_CHOICE). All fields must be provided in the
        update. Changes are tracked in the audit log for compliance.


        RBAC: requires GroupQuestions.Manage
      tags:
        - Group Questions
      parameters:
        - description: The unique identifier of the group containing the question
          example: gr_01hz1f0kw36f82k9s4nzpc4s92n
          required: true
          name: groupId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: The unique identifier of the question to update
          example: qu_01hz1f0gs9fe4a37jzvzn9m96k
          required: true
          name: questionId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuestionUpdate'
        required: true
      responses:
        '200':
          description: Successfully updated the question
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Question'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ValidationError
                message: Invalid parameters
          description: Invalid parameters
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security: []
    delete:
      summary: Delete a group question
      description: >-
        Permanently removes a question from the group's entry requirements.
        Requires GroupQuestions.Manage permission. This action cannot be undone.
        Any existing answers to this question are preserved for audit purposes
        but will not be evaluated for new join requests. The deletion is
        recorded in the audit log.


        RBAC: requires GroupQuestions.Manage
      tags:
        - Group Questions
      parameters:
        - description: The unique identifier of the group containing the question
          example: gr_01hz1f0kw36f82k9s4nzpc4s92n
          required: true
          name: groupId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: The unique identifier of the question to delete
          example: qu_01hz1f0gs9fe4a37jzvzn9m96k
          required: true
          name: questionId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Question successfully deleted
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security: []
  /api/v1/groups/{groupId}/reports/delete-posts:
    post:
      summary: Remove posts from all reports and auto-close empty reports
      description: >-
        Removes specified posts from all reports that reference them. If a
        report no longer has any posts after removal, it is automatically
        closed/resolved. This is typically used after deleting reported content.
        Returns the count of reports that were auto-closed. The current user is
        recorded as having taken action on auto-closed reports.


        RBAC: requires GroupReports.Manage
      tags:
        - Group Reports
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/TypeId'
        required: true
      responses:
        '200':
          description: >-
            Operation successful, returns number of reports that were
            auto-closed
          content:
            text/plain:
              schema:
                format: int32
                type: integer
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupContextIsEmpty
                message: Group context is not present
          description: Group context is not present
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                NotGroupMember:
                  description: The user must be a member of the group
                  value:
                    errorCode: NotGroupMember
                    message: The user must be a member of the group
                RBACInsufficientPermissions:
                  description: Insufficient permissions to perform this operation
                  value:
                    errorCode: RBACInsufficientPermissions
                    message: Insufficient permissions to perform this operation
          description: Forbidden
      security: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
  /api/v1/groups/{groupId}/reports/list:
    get:
      summary: List group moderation reports
      description: >-
        Returns the reports scoped to the current group. Supports filtering by
        reported user, post, and resolution status. Only members with
        GroupReports.Read or Manage can access this list.


        RBAC:

        - requires ANY of GroupReports.Read, GroupReports.Manage
      tags:
        - Group Reports
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: >-
            Filter by resolution status. true = open reports, false = resolved,
            omit = all
          required: false
          name: open
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Filter by reported post ID
          required: false
          name: postId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Filter by reported user ID
          required: false
          name: userId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportsPaginatedResponse'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupContextIsEmpty
                message: Group context is not present
          description: Group context is not present
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                NotGroupMember:
                  description: The user must be a member of the group
                  value:
                    errorCode: NotGroupMember
                    message: The user must be a member of the group
                RBACInsufficientPermissions:
                  description: Insufficient permissions to perform this operation
                  value:
                    errorCode: RBACInsufficientPermissions
                    message: Insufficient permissions to perform this operation
          description: Forbidden
      security: []
  /api/v1/groups/{groupId}/reports/{reportId}:
    get:
      summary: View specific group report
      description: >-
        Returns the full details for a single report within the current group
        scope.


        RBAC:

        - requires ANY of GroupReports.Read, GroupReports.Manage
      tags:
        - Group Reports
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupContextIsEmpty
                message: Group context is not present
          description: Group context is not present
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                NotGroupMember:
                  description: The user must be a member of the group
                  value:
                    errorCode: NotGroupMember
                    message: The user must be a member of the group
                RBACInsufficientPermissions:
                  description: Insufficient permissions to perform this operation
                  value:
                    errorCode: RBACInsufficientPermissions
                    message: Insufficient permissions to perform this operation
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ReportNotFound
                message: The specified report not found
          description: The specified report not found
      security: []
  /api/v1/groups/{groupId}/reports/{reportId}/add-note:
    post:
      summary: Add note to group report
      description: |-
        Appends a moderation note to the report for internal collaboration.

        RBAC: requires GroupReports.Manage
      tags:
        - Group Reports
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          text/plain:
            schema:
              type: string
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupContextIsEmpty
                message: Group context is not present
          description: Group context is not present
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                NotGroupMember:
                  description: The user must be a member of the group
                  value:
                    errorCode: NotGroupMember
                    message: The user must be a member of the group
                RBACInsufficientPermissions:
                  description: Insufficient permissions to perform this operation
                  value:
                    errorCode: RBACInsufficientPermissions
                    message: Insufficient permissions to perform this operation
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ReportNotFound
                message: The specified report not found
          description: The specified report not found
      security: []
  /api/v1/groups/{groupId}/reports/{reportId}/remove-note:
    post:
      summary: Remove note from group report
      description: |-
        Removes a moderation note by index.

        RBAC: requires GroupReports.Manage
      tags:
        - Group Reports
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Zero-based note index
          required: true
          name: index
          in: query
          schema:
            format: int32
            type: integer
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                GroupContextIsEmpty:
                  description: Group context is not present
                  value:
                    errorCode: GroupContextIsEmpty
                    message: Group context is not present
                ConstraintViolation:
                  description: A request parameter constraint was violated
                  value:
                    errorCode: ConstraintViolation
                    message: A request parameter constraint was violated
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                NotGroupMember:
                  description: The user must be a member of the group
                  value:
                    errorCode: NotGroupMember
                    message: The user must be a member of the group
                RBACInsufficientPermissions:
                  description: Insufficient permissions to perform this operation
                  value:
                    errorCode: RBACInsufficientPermissions
                    message: Insufficient permissions to perform this operation
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ReportNotFound
                message: The specified report not found
          description: The specified report not found
      security: []
  /api/v1/groups/{groupId}/reports/{reportId}/reopen:
    post:
      summary: Reopen a resolved group report
      description: |-
        Clears resolution state so the report can be handled again.

        RBAC: requires GroupReports.Manage
      tags:
        - Group Reports
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupContextIsEmpty
                message: Group context is not present
          description: Group context is not present
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                NotGroupMember:
                  description: The user must be a member of the group
                  value:
                    errorCode: NotGroupMember
                    message: The user must be a member of the group
                RBACInsufficientPermissions:
                  description: Insufficient permissions to perform this operation
                  value:
                    errorCode: RBACInsufficientPermissions
                    message: Insufficient permissions to perform this operation
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ReportNotFound
                message: The specified report not found
          description: The specified report not found
      security: []
  /api/v1/groups/{groupId}/reports/{reportId}/resolve:
    post:
      summary: Resolve a group report
      description: |-
        Marks the report as resolved by the current moderator.

        RBAC: requires GroupReports.Manage
      tags:
        - Group Reports
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupContextIsEmpty
                message: Group context is not present
          description: Group context is not present
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                NotGroupMember:
                  description: The user must be a member of the group
                  value:
                    errorCode: NotGroupMember
                    message: The user must be a member of the group
                RBACInsufficientPermissions:
                  description: Insufficient permissions to perform this operation
                  value:
                    errorCode: RBACInsufficientPermissions
                    message: Insufficient permissions to perform this operation
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ReportNotFound
                message: The specified report not found
          description: The specified report not found
      security: []
  /api/v1/groups/{groupId}/rules:
    get:
      summary: Get all rules for a group
      description: >-
        Retrieves the complete list of rules for a specific group. Rules are
        returned in order based on their ordering value (lowest first). This
        endpoint is publicly accessible as group rules should be visible to
        potential members before joining. Each rule includes its text content,
        explanatory hint, and display ordering.
      tags:
        - Group Rules
      parameters:
        - description: The unique identifier of the group whose rules to retrieve
          example: gr_01hz1f0kw36f82k9s4nzpc4s92n
          required: true
          name: groupId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: List of all group rules sorted by ordering value
          content:
            application/json:
              example:
                - id: rl_01hz1f0gs9fe4a37jzvzn9m96k
                  text: Be respectful to all members
                  hint: Treat all group members with respect and kindness
                  ordering: 1000
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Rule'
      security: []
    post:
      summary: Create a new group rule
      description: >-
        Creates a new rule for the specified group. Requires
        GroupSettings.Manage permission. The rule will be assigned a unique ID
        and added to the group's rule list. Rules are used to establish
        community guidelines and expected behavior. An audit log entry is
        created for this action.


        RBAC: requires GroupSettings.Manage
      tags:
        - Group Rules
      parameters:
        - description: The unique identifier of the group to add the rule to
          example: gr_01hz1f0kw36f82k9s4nzpc4s92n
          required: true
          name: groupId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Additional explanation or context for the rule (max 500 characters)
          example: >-
            This includes no personal attacks, harassment, or discriminatory
            language
          required: true
          name: hint
          in: query
          schema:
            type: string
        - description: Display order for the rule (lower values appear first)
          example: 1000
          required: true
          name: ordering
          in: query
          schema:
            format: int32
            minimum: 0
            type: integer
        - description: The rule text that members must follow (max 500 characters)
          example: Be respectful to all members
          required: true
          name: text
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Successfully created the new rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ValidationError
                message: Invalid parameters
          description: Invalid parameters
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/groups/{groupId}/rules/reorder:
    post:
      summary: Reorder multiple group rules
      description: >-
        Batch updates the display ordering of multiple rules within a group.
        This endpoint allows efficient reordering of rules without individual
        API calls. Requires GroupSettings.Manage permission. Each reordering
        operation is tracked in the audit log. Rules not included in the request
        maintain their current ordering. Returns all group rules with updated
        ordering values.


        RBAC: requires GroupSettings.Manage
      tags:
        - Group Rules
      parameters:
        - description: The unique identifier of the group whose rules to reorder
          example: gr_01hz1f0kw36f82k9s4nzpc4s92n
          required: true
          name: groupId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RuleOrderingRequest'
        required: true
      responses:
        '200':
          description: All group rules with updated ordering
          content:
            application/json:
              schema:
                description: Complete list of group rules reflecting the new ordering
                type: array
                items:
                  $ref: '#/components/schemas/Rule'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ValidationError
                message: Invalid parameters
          description: Invalid parameters
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/groups/{groupId}/rules/{id}:
    delete:
      summary: Delete a group rule
      description: >-
        Permanently removes a rule from the group. Requires GroupSettings.Manage
        permission. This action cannot be undone. The deletion is recorded in
        the audit log. Returns 404 if the rule doesn't exist or doesn't belong
        to the specified group.


        RBAC: requires GroupSettings.Manage
      tags:
        - Group Rules
      parameters:
        - description: The unique identifier of the group containing the rule
          example: gr_01hz1f0kw36f82k9s4nzpc4s92n
          required: true
          name: groupId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: The unique identifier of the rule to delete
          example: rl_01hz1f0gs9fe4a37jzvzn9m96k
          required: true
          name: id
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Rule successfully deleted
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security: []
  /api/v1/groups/{groupId}/rules/{ruleId}:
    put:
      summary: Update an existing group rule
      description: >-
        Modifies an existing rule's text, hint, or ordering. Requires
        GroupSettings.Manage permission. The entire rule content must be
        provided in the update request. Changes are tracked in the audit log for
        compliance and moderation purposes. Returns 404 if the rule doesn't
        exist.


        RBAC: requires GroupSettings.Manage
      tags:
        - Group Rules
      parameters:
        - description: The unique identifier of the group containing the rule
          example: gr_01hz1f0kw36f82k9s4nzpc4s92n
          required: true
          name: groupId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: The unique identifier of the rule to update
          example: rl_01hz1f0gs9fe4a37jzvzn9m96k
          required: true
          name: ruleId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuleUpdate'
        required: true
      responses:
        '200':
          description: Successfully updated the rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ValidationError
                message: Invalid parameters
          description: Invalid parameters
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security: []
  /api/v1/groups/{groupId}/settings:
    put:
      summary: Update group settings
      description: >-
        Update multiple group settings in a single operation. Each setting must
        be provided as a complete object with all required fields. Partial
        updates are not supported to ensure data consistency and prevent
        configuration errors.


        RBAC: requires GroupSettings.Manage
      tags:
        - Group Settings
      requestBody:
        description: >-
          settings objects to be updated. complete objects must be provided -
          partial updates are not allowed.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupSettings'
        required: true
      responses:
        '200':
          description: number of updated settings
          content:
            application/json:
              example:
                updated: 3
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                SettingsInvalidKeyProvided:
                  description: Unknown settings key(s) %s
                  value:
                    errorCode: SettingsInvalidKeyProvided
                    message: Unknown settings key(s) %s
                SettingsKeyNotProvided:
                  description: No settings keys were provided
                  value:
                    errorCode: SettingsKeyNotProvided
                    message: No settings keys were provided
                SettingsValuesNotProvided:
                  description: No settings values were provided
                  value:
                    errorCode: SettingsValuesNotProvided
                    message: No settings values were provided
                SettingsPartialUpdateNotAllowed:
                  description: 'Partial updates are not allowed: %s'
                  value:
                    errorCode: SettingsPartialUpdateNotAllowed
                    message: 'Partial updates are not allowed: %s'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsForbidden
                message: Access denied for settings
          description: Access denied for settings
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsNotUpdated
                message: Failed to update settings
          description: Failed to update settings
      security:
        - header: []
      parameters:
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
    get:
      summary: Get group settings
      description: >-
        Retrieve specific group settings by their keys. Returns a JSON object
        mapping setting names to their configured values. Only settings that the
        authenticated user has permission to read will be included in the
        response.
      tags:
        - Group Settings
      parameters:
        - description: >-
            Comma-separated list of setting keys to retrieve. Each key must
            correspond to a valid group setting definition registered in the
            system.


            Available keys are:


            ```group.join.questions```


            ```group.membership```


            ```group.moderation```


            ```group.privacy```
          name: keys
          required: true
          in: query
          schema:
            type: array
            items:
              type: string
          example: group.join.questions,group.membership
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/GroupSettings'
          description: Response GroupSettings
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                SettingsInvalidKeyProvided:
                  description: Unknown settings key(s) %s
                  value:
                    errorCode: SettingsInvalidKeyProvided
                    message: Unknown settings key(s) %s
                SettingsKeyNotProvided:
                  description: No settings keys were provided
                  value:
                    errorCode: SettingsKeyNotProvided
                    message: No settings keys were provided
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsForbidden
                message: Access denied for settings
          description: Access denied for settings
      security:
        - header: []
    delete:
      summary: Delete group settings
      description: >-
        Remove specific group settings by their keys. This operation will
        permanently delete the specified settings and revert them to their
        default values. Use with caution as deleted settings cannot be
        recovered.


        RBAC: requires GroupSettings.Manage
      tags:
        - Group Settings
      parameters:
        - description: >-
            Comma-separated list of setting keys to delete. Each key must
            correspond to a valid group setting that exists for this group.


            Available keys are:


            ```group.join.questions```


            ```group.membership```


            ```group.moderation```


            ```group.privacy```
          name: keys
          required: true
          in: query
          schema:
            type: array
            items:
              type: string
          example: group.join.questions,group.membership
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: number of deleted settings
          content:
            application/json:
              example:
                deleted: 3
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                SettingsKeyNotProvided:
                  description: No settings keys were provided
                  value:
                    errorCode: SettingsKeyNotProvided
                    message: No settings keys were provided
                SettingsInvalidKeyProvided:
                  description: Unknown settings key(s) %s
                  value:
                    errorCode: SettingsInvalidKeyProvided
                    message: Unknown settings key(s) %s
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsForbidden
                message: Access denied for settings
          description: Access denied for settings
      security:
        - header: []
  /api/v1/groups/{groupId}/users:
    get:
      summary: Get group members as User objects
      description: |2-

                    Retrieves the list of all members in the specified group.
                    Public groups are accessible to all authenticated users, Private groups accessible to members only.
                    Supports sorting by join time, posts, or relationship to current user.
                    Supports role filtering and pagination.
                
      tags:
        - Group Members
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Sort order (case-insensitive)
          required: false
          name: order
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/SortOrder'
            nullable: true
        - description: Role filter (case-insensitive)
          required: false
          name: role
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/GroupMemberRoleFilter'
            nullable: true
        - description: Sort field (case-insensitive)
          required: false
          name: sort
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/GroupMembersSortBy'
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: groupId
          description: The unique identifier of the group
          required: true
          example: gr_01hz1f0kw36f82k9s4nzpc4s33n
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: List of users who are members of the group
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupContextIsEmpty
                message: Group context is not present
          description: Group context is not present
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
                NotGroupMember:
                  description: The user must be a member of the group
                  value:
                    errorCode: NotGroupMember
                    message: The user must be a member of the group
                GroupMemberListNotPublic:
                  description: Group member list is not visible to non-members
                  value:
                    errorCode: GroupMemberListNotPublic
                    message: Group member list is not visible to non-members
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: GroupNotFound
                message: Group not found
          description: Group not found
      security: []
  /api/v1/import:
    get:
      summary: List user's import jobs
      description: >-
        Returns a list of all import jobs created by the authenticated user,
        including their current status and results.
      tags:
        - Import
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BulkImport'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
    post:
      summary: Import data from CSV file
      description: >-
        Uploads and processes a CSV file for bulk import of data such as
        followers, blocks, or mutes from other platforms. The import is
        processed asynchronously after upload.
      tags:
        - Import
      parameters:
        - name: overwrite
          in: query
          schema:
            type: boolean
            nullable: true
        - name: type
          in: query
          schema:
            $ref: '#/components/schemas/BulkImportType'
          required: true
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - file
              type: object
              properties:
                file:
                  format: binary
                  maxLength: 20971520
                  minLength: 1
                  type: string
        required: true
      responses:
        '200':
          description: The ID of the created import job
          content:
            text/plain:
              schema:
                type: integer
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ClientError
                message: Invalid request from client
          description: Invalid request from client
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/import/start/{id}:
    post:
      summary: Start import processing
      description: >-
        Begins processing a previously uploaded import job. The import must be
        in PENDING state to be started.
      tags:
        - Import
      parameters:
        - name: id
          in: path
          required: true
          schema:
            format: int64
            type: integer
      responses:
        '200':
          description: Import job started successfully
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ClientError
                message: Invalid request from client
          description: Invalid request from client
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: Forbidden
                message: No access to the resource
          description: No access to the resource
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/import/{id}:
    get:
      summary: Get import job details
      description: >-
        Retrieves the current status and details of a specific import job,
        including processing progress and any errors.
      tags:
        - Import
      parameters:
        - name: id
          in: path
          required: true
          schema:
            format: int64
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkImport'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: Forbidden
                message: No access to the resource
          description: No access to the resource
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/instance:
    get:
      summary: Get instance information
      description: >-
        Returns comprehensive server instance metadata including domain,
        version, build information, registration configuration, and server
        rules. Useful for clients to understand server capabilities and
        requirements.
      tags:
        - Instance
      responses:
        '200':
          description: Instance info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
      security: []
  /api/v1/instance/countries:
    get:
      summary: Get country information
      description: >-
        Returns country data including names (common/official/native), flags,
        and phone codes. Data is cached in Redis with 7-day TTL and fetched from
        external API if not cached. Falls back to local file if API is
        unavailable. Used for country selection in user profiles and phone
        number validation.
      tags:
        - Instance
      responses:
        '200':
          description: List of countries info about name, phone number and flag
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CountryInfo'
      security: []
  /api/v1/instance/domains:
    get:
      summary: Search compatible federated domains
      description: >-
        Returns a list of federated server domains compatible with specified
        software. Filters domains by prefix matching for autocomplete
        functionality. Useful for discovering servers running specific
        ActivityPub software (Mastodon, Pleroma, etc.). Results are cached for
        performance.
      tags:
        - Instance
      parameters:
        - description: domain
          required: true
          name: domain
          in: query
          schema:
            maxLength: 64
            minLength: 1
            type: string
        - description: limit
          required: false
          name: limit
          in: query
          schema:
            format: int64
            minimum: 0
            exclusiveMinimum: true
            type: integer
            nullable: true
        - description: software
          required: true
          name: software
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Domains list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
      security: []
  /api/v1/instance/extended_description:
    get:
      summary: Get extended server description
      description: >-
        Returns detailed 'about' information for this server instance. Includes
        formatted HTML content describing the server's purpose and policies.
        Content is admin-configurable (feature pending implementation).
      tags:
        - Instance
      responses:
        '200':
          description: Extended Instance info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
      security: []
  /api/v1/instance/supported_languages:
    get:
      summary: Get supported languages
      description: >-
        Returns all languages supported by the platform for content and UI
        translation. Each language includes its ISO code and native name. Used
        for language selection in user preferences and content language
        detection. Languages are used by the translation API for multi-language
        support.
      tags:
        - Instance
      responses:
        '200':
          description: List of supported languages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupportedLanguage'
      security: []
  /api/v1/instance/timezones:
    get:
      summary: Get supported timezones
      description: >-
        Returns a comprehensive list of all supported timezones with metadata.
        Includes timezone abbreviations, UTC offsets, DST information, and
        display text. Used for user timezone selection in profile settings.
      tags:
        - Instance
      responses:
        '200':
          description: List of timezones
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimezoneInfo'
      security: []
  /api/v1/jobs/list-jobs:
    get:
      summary: List all job types
      description: >-
        Returns a list of all available job types in the system. Supports
        pagination.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Jobs
      parameters:
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
      responses:
        '200':
          description: Paginated list of job types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListResult'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/jobs/list-stats:
    get:
      summary: Get statistics for a specific queue
      description: >-
        Returns detailed statistics for a specific job queue including counts of
        finished, failed, active, submitted, and retry jobs.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Jobs
      parameters:
        - name: queue
          in: query
          schema:
            pattern: \S
            type: string
          required: true
      responses:
        '200':
          description: Queue statistics with job counts by status
          content:
            application/json:
              schema:
                type: object
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/jobs/list-stats-all:
    get:
      summary: Get statistics for all queues
      description: >-
        Returns aggregated statistics across all job queues including counts of
        finished, failed, active, submitted, scheduled, and retry jobs.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Jobs
      responses:
        '200':
          description: Aggregated statistics for all queues
          content:
            application/json:
              schema:
                type: object
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/jobs/lists:
    get:
      summary: List jobs by status in a queue
      description: >-
        Returns a paginated list of jobs with a specific status (finished,
        failed, active, submitted, retries, schedule) from a specific queue.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Jobs
      parameters:
        - name: limit
          in: query
          schema:
            format: int64
            type: integer
            nullable: true
        - name: listKind
          in: query
          schema:
            pattern: \S
            type: string
          required: true
        - name: offset
          in: query
          schema:
            format: int64
            type: integer
            nullable: true
        - name: queue
          in: query
          schema:
            pattern: \S
            type: string
          required: true
      responses:
        '200':
          description: List of jobs with the specified status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedisJobsResult'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: JobsInvalidKind
                message: The specified job kind is incorrect
          description: The specified job kind is incorrect
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/jobs/stats:
    get:
      summary: Get overall job statistics
      description: >-
        Returns aggregated statistics for all finished and failed jobs across
        all queues. Requires Jobs.Read or Jobs.Manage permission.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Jobs
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OverallStats'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/jobs/stats-per-day:
    get:
      summary: Get daily job statistics
      description: >-
        Returns job statistics broken down by day for the specified number of
        past days. Can be filtered by queue or aggregated across all queues.


        RBAC:

        - requires ANY of Jobs.Read, Jobs.Manage
      tags:
        - Jobs
      parameters:
        - name: lastDays
          in: query
          schema:
            format: int32
            maximum: 100
            minimum: 1
            type: integer
        - name: queue
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Daily statistics for finished and failed jobs
          content:
            application/json:
              schema:
                type: object
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ConstraintViolation
                message: A request parameter constraint was violated
          description: A request parameter constraint was violated
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/links:
    get:
      summary: Generate link preview
      description: >-
        Fetches and returns metadata for a given URL to create a rich preview
        card. Extracts title, description, image, author, and other
        OpenGraph/Twitter Card metadata. Results are cached for performance.
        Returns error if URL is unreachable or has no metadata. The URL must be
        properly formatted and accessible.
      tags:
        - Link Preview
      parameters:
        - name: url
          in: query
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Link preview card with extracted metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: LinkPreviewNotAvailable
                message: Link preview not available
          description: Link preview not available
      security: []
  /api/v1/lists:
    get:
      summary: Get authenticated user's lists
      description: >-
        Returns all lists created by the authenticated user for organizing
        followed accounts.
      tags:
        - Lists
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UsersList'
      security:
        - header: []
    post:
      summary: Create a new list
      description: >-
        Creates a new list for organizing followed accounts. Lists can be public
        or private.
      tags:
        - Lists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserListCreate'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersList'
        '400':
          description: Bad Request
      security:
        - header: []
  /api/v1/lists/{listId}:
    put:
      summary: Update list properties
      description: >-
        Updates the name, privacy setting, or other properties of an existing
        list. Only the list owner can update it.
      tags:
        - Lists
      parameters:
        - name: listId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserListCreate'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersList'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserListNotFound
                message: The user list could not be found
          description: The user list could not be found
      security:
        - header: []
    get:
      summary: Get list details by ID
      description: >-
        Retrieves details of a specific list including its name, privacy
        setting, and metadata. Private lists can only be accessed by their
        owner.
      tags:
        - Lists
      parameters:
        - name: listId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersList'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserListNotFound
                message: The user list could not be found
          description: The user list could not be found
      security:
        - header: []
    delete:
      summary: Delete a list
      description: >-
        Permanently deletes a list and removes all user associations. Only the
        list owner can delete it.
      tags:
        - Lists
      parameters:
        - name: listId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserListCantDeleteOthers
                message: Cannot delete a list belonging to another user
          description: Cannot delete a list belonging to another user
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserListNotFound
                message: The user list could not be found
          description: The user list could not be found
      security:
        - header: []
  /api/v1/lists/{listId}/users:
    get:
      summary: Get users in a list
      description: >-
        Returns all users that have been added to a specific list. Private lists
        can only be accessed by their owner.
      tags:
        - Lists
      parameters:
        - name: listId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserListNotFound
                message: The user list could not be found
          description: The user list could not be found
      security:
        - header: []
  /api/v1/lists/{listId}/users/{userId}:
    delete:
      summary: Remove user from list
      description: Removes a user from a list. Only the list owner can remove users.
      tags:
        - Lists
      parameters:
        - name: listId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersList'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserListCantAdd
                message: Failed to add the user to the list
          description: Failed to add the user to the list
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UserListCantChangeOthers:
                  description: Cannot update a list belonging to another user
                  value:
                    errorCode: UserListCantChangeOthers
                    message: Cannot update a list belonging to another user
                UserListCantDeleteOthers:
                  description: Cannot delete a list belonging to another user
                  value:
                    errorCode: UserListCantDeleteOthers
                    message: Cannot delete a list belonging to another user
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UserListNotFound:
                  description: The user list could not be found
                  value:
                    errorCode: UserListNotFound
                    message: The user list could not be found
                UserListUserNotFound:
                  description: The specified user not found in the list
                  value:
                    errorCode: UserListUserNotFound
                    message: The specified user not found in the list
          description: Not Found
      security:
        - header: []
    post:
      summary: Add user to list
      description: >-
        Adds a user to a list for organization and filtering purposes. Only
        followed users can be added to lists. Only the list owner can add users.
      tags:
        - Lists
      parameters:
        - name: listId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersList'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserListCantAdd
                message: Failed to add the user to the list
          description: Failed to add the user to the list
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserListCantChangeOthers
                message: Cannot update a list belonging to another user
          description: Cannot update a list belonging to another user
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserListNotFound
                message: The user list could not be found
          description: The user list could not be found
      security:
        - header: []
  /api/v1/metrics:
    get:
      summary: Get metrics for a specified time period
      description: >-
        Retrieves metrics data for the events stream within a specified time
        period. Supports both predefined periods (last day/week/month) and
        custom date ranges.


        RBAC:

        - requires ANY of Federation.Read, Federation.Manage
      tags:
        - Metrics
      parameters:
        - description: >-
            Start time for custom date range (ISO 8601 format). Use with 'to'
            parameter.
          required: false
          name: from
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/Instant'
            nullable: true
        - description: 'Predefined time period. Options: LAST_DAY, LAST_WEEK, LAST_MONTH'
          required: false
          name: period
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/MetricsPeriod'
            nullable: true
        - description: >-
            End time for custom date range (ISO 8601 format). Use with 'from'
            parameter.
          required: false
          name: to
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/Instant'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MetricsData'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ConstraintViolation
                message: A request parameter constraint was violated
          description: A request parameter constraint was violated
      security: []
  /api/v1/metrics/totals:
    get:
      summary: Get current server totals
      description: |-
        Returns the current total counts of users and posts on the server.

        RBAC:
        - requires ANY of Federation.Read, Federation.Manage
      tags:
        - Metrics
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerTotals'
      security: []
  /api/v1/mute:
    get:
      summary: List all muted users
      description: >-
        Returns a paginated list of all users currently muted by the
        authenticated user.
      tags:
        - Mutes
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
      security:
        - header: []
  /api/v1/mute/{userId}:
    delete:
      summary: Unmute a previously muted user
      description: >-
        Removes the mute on a specific user, allowing their content to appear
        again in timelines and notifications.
      tags:
        - Mutes
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: MuteNotMuted
                message: The user is not muted
          description: The user is not muted
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security:
        - header: []
    post:
      summary: Mute a specific user
      description: >-
        Hides all content from a specific user. Can optionally set an expiration
        time for the mute. Muted users' posts will not appear in timelines or
        notifications.
      tags:
        - Mutes
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Seconds after which mute should expire
          required: false
          name: duration
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: MuteSelf
                message: A user cannot mute themselves
          description: A user cannot mute themselves
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security:
        - header: []
  /api/v1/notes:
    put:
      summary: Set or update note for a user
      description: >-
        Creates or updates a personal note about another user. These notes are
        private and only visible to the authenticated user who created them.
      tags:
        - Notes
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NoteUpdate'
        required: true
      responses:
        '200':
          description: Note has been updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserNote'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: NoteForSelf
                message: Cannot create a note for oneself
          description: Cannot create a note for oneself
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: DBError
                message: An unexpected database error
          description: An unexpected database error
      security:
        - header: []
    get:
      summary: Get notes for multiple users
      description: >-
        Retrieves personal notes the authenticated user has created about
        specified users. Returns notes for multiple users in a single request.
      tags:
        - Notes
      parameters:
        - description: List of user ids
          examples: {}
          name: userIds
          required: true
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Notes have been fetched successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserNote'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/notes/{userId}:
    delete:
      summary: Delete note for a user
      description: Permanently deletes a personal note about a specific user.
      tags:
        - Notes
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Note has been deleted successfully
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security:
        - header: []
  /api/v1/notifications:
    get:
      summary: Returns user's notifications
      description: >-
        Retrieves the user's notifications with filtering options for types,
        excludeTypes and status
      tags:
        - Notifications
      parameters:
        - name: excludeTypes
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/NotificationType'
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - name: status
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/NotificationStatus'
            nullable: true
        - name: types
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/NotificationType'
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: Notifications
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Notification'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/notifications/count:
    get:
      summary: Returns notifications count
      description: >-
        Gets the count of user's notifications with filtering options for types,
        excludeTypes and status
      tags:
        - Notifications
      parameters:
        - name: excludeTypes
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/NotificationType'
            nullable: true
        - name: status
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/NotificationStatus'
            nullable: true
        - name: types
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/NotificationType'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: integer
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/notifications/mark-all:
    post:
      summary: Mark all notifications as read/unread
      description: >-
        Updates the status of all notifications for the authenticated user to
        either read or unread
      tags:
        - Notifications
      parameters:
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/NotificationStatus'
          required: true
      responses:
        '200':
          description: Number of notifications changed
          content:
            application/json:
              schema:
                type: integer
      security:
        - header: []
  /api/v1/notifications/{id}:
    get:
      summary: Returns user's notification by id
      description: Retrieves a specific notification by its ID for the authenticated user
      tags:
        - Notifications
      parameters:
        - description: Notification id
          required: true
          name: id
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: Notification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notification'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: NotificationNotFound
                message: The specified notification not found
          description: The specified notification not found
      security:
        - header: []
  /api/v1/notifications/{id}/mark:
    post:
      summary: Mark notification as read/unread by id
      description: Updates the status of a specific notification to either read or unread
      tags:
        - Notifications
      parameters:
        - description: Notification id
          required: true
          name: id
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/NotificationStatus'
          required: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: Notification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notification'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: NotificationNotFound
                message: The specified notification not found
          description: The specified notification not found
      security:
        - header: []
  /api/v1/passkeys:
    get:
      summary: List registered passkeys
      description: Returns passkey credentials for current selected user
      tags:
        - Passkeys
      responses:
        '200':
          description: List of credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Passkey'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/passkeys/begin-auth:
    get:
      summary: Begin passkey authentication
      description: >-
        Generates and returns WebAuthn assertion (request) options. The server
        will set cookies to maintain the authentication challenge context.
        Optionally restrict by username.
      tags:
        - Passkeys
      parameters:
        - name: username
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Request options
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicKeyCredentialRequestOptions'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ClientError
                message: Invalid request from client
          description: Invalid request from client
      security: []
  /api/v1/passkeys/begin-register:
    get:
      summary: Begin passkey registration
      description: >-
        Generates and returns WebAuthn creation options for the current user.
        The server will set cookies to maintain the registration challenge
        context.
      tags:
        - Passkeys
      responses:
        '200':
          description: Creation options
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicKeyCredentialCreationOptions'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ClientError
                message: Invalid request from client
          description: Invalid request from client
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/passkeys/finish-auth:
    post:
      summary: Finish passkey authentication
      description: >-
        Verifies the authenticator assertion against the stored challenge and
        returns a session token on success.
      tags:
        - Passkeys
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonObject'
        required: true
      responses:
        '200':
          description: Session key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ClientError
                message: Invalid request from client
          description: Invalid request from client
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UserBadCreds:
                  description: Invalid user credentials provided
                  value:
                    errorCode: UserBadCreds
                    message: Invalid user credentials provided
                UserMissingCreds:
                  description: No credentials provided
                  value:
                    errorCode: UserMissingCreds
                    message: No credentials provided
          description: Unauthorized
      security: []
  /api/v1/passkeys/finish-register:
    post:
      summary: Finish passkey registration
      description: >-
        Validates the authenticator attestation response against the stored
        challenge and persists the new credential.
      tags:
        - Passkeys
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonObject'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Passkey'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ClientError
                message: Invalid request from client
          description: Invalid request from client
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/passkeys/{credentialId}:
    delete:
      summary: Remove a registered passkey
      description: Deletes a credential by id. Cannot remove last remaining login method.
      tags:
        - Passkeys
      parameters:
        - name: credentialId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                CantRemoveLastLogin:
                  description: Cannot remove the last login option
                  value:
                    errorCode: CantRemoveLastLogin
                    message: Cannot remove the last login option
                PasskeyNoAccess:
                  description: No access to the passkey
                  value:
                    errorCode: PasskeyNoAccess
                    message: No access to the passkey
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PasskeyNotFound
                message: Passkey not found
          description: Passkey not found
      security:
        - header: []
  /api/v1/polls/{pollId}/refresh:
    post:
      summary: Refresh poll results
      description: >-
        Refreshes poll results from the remote server if the poll is from a
        federated instance and the results may be stale. Returns the updated
        poll with current vote counts.
      tags:
        - Polls
      parameters:
        - name: pollId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Poll'
      security:
        - header: []
  /api/v1/polls/{pollId}/vote:
    post:
      summary: Vote in a poll
      description: >-
        Submit vote(s) for a poll. Multiple choices can be selected if the poll
        allows it. Users cannot vote in their own polls or vote multiple times.
      tags:
        - Polls
      parameters:
        - name: pollId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                format: int32
                type: integer
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                PollExpired:
                  description: The poll has already ended
                  value:
                    errorCode: PollExpired
                    message: The poll has already ended
                PollSelfVote:
                  description: You cannot vote in your own polls
                  value:
                    errorCode: PollSelfVote
                    message: You cannot vote in your own polls
                PollAlreadyVoted:
                  description: You have already voted on this poll
                  value:
                    errorCode: PollAlreadyVoted
                    message: You have already voted on this poll
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                PostNotFound:
                  description: The specified post not found
                  value:
                    errorCode: PostNotFound
                    message: The specified post not found
                PollNotFound:
                  description: The specified poll not found
                  value:
                    errorCode: PollNotFound
                    message: The specified poll not found
          description: Not Found
      security:
        - header: []
  /api/v1/posts:
    get:
      summary: Get posts feed
      description: >-
        Returns posts based on various filters. For authenticated users, shows
        their personalized feed. For unauthenticated users, shows public posts
        only. Supports filtering by user, owner, tags, lists, bookmarks, and
        more. Can include comments, translations, and various metadata.
      tags:
        - Posts
      parameters:
        - description: Return results across all scopes when using bookmarkedOnly
          required: false
          name: all
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Return bookmarked only
          required: false
          name: bookmarkedOnly
          in: query
          schema:
            type: boolean
            nullable: true
        - description: >-
            Filter posts by forum tags (comma-separated, AND logic - posts must
            have ALL tags)
          required: false
          name: forumTags
          in: query
          schema:
            type: array
            items:
              type: string
            nullable: true
        - description: Include bookmark field
          required: false
          name: includeBookmarkStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include comments
          required: false
          name: includeComments
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include follow status
          required: false
          name: includeFollowStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include pinned status
          required: false
          name: includePinnedStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include direct reply if present
          required: false
          name: includeReply
          in: query
          schema:
            type: boolean
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Limit first level comment paging count
          required: false
          name: limitFirstLevelComments
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Limit second level comment paging count
          required: false
          name: limitSecondLevelComments
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: List posts by a user list
          required: false
          name: listId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Max comment level depth
          required: false
          name: maxLevel
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Min comment level depth
          required: false
          name: minLevel
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: List specific owner's posts
          required: false
          name: ownerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Filter posts by ownerType
          required: false
          name: ownerType
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/PostOwnerType'
            nullable: true
        - description: Filter by pinned status. Applied only if ?userId is present
          name: pinned
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/PinnedParam'
            nullable: true
        - description: Filter by repost kind
          name: repostKind
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/RepostParam'
            nullable: true
        - description: List only reposts of specified post
          required: false
          name: repostOf
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Return reposts only
          required: false
          name: repostsOnly
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Search posts by text
          required: false
          name: search
          in: query
          schema:
            type: string
            nullable: true
        - description: If false - force showing reposts non-aggregated
          required: false
          name: skipReposts
          in: query
          schema:
            type: boolean
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: Search posts by a tag
          required: false
          name: tag
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: List specific user's posts. Used for User/Profile feed
          required: false
          name: userId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: List specific user's posts
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
        - description: Include repostedBy. Default true
          name: withRepostedBy
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include translation
          required: false
          name: withTranslation
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include trends
          name: withTrends
          in: query
          schema:
            type: boolean
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostsNoOwnerType
                message: An ownerType must be provided
          description: An ownerType must be provided
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ForumNotFound:
                  description: The specified forum not found
                  value:
                    errorCode: ForumNotFound
                    message: The specified forum not found
                CategoryNotFound:
                  description: The specified category not found
                  value:
                    errorCode: CategoryNotFound
                    message: The specified category not found
                EventNotFound:
                  description: The specified event not found
                  value:
                    errorCode: EventNotFound
                    message: The specified event not found
                PostsListNotFound:
                  description: The specified list not found
                  value:
                    errorCode: PostsListNotFound
                    message: The specified list not found
          description: Not Found
      security:
        - header: []
    post:
      summary: Create a new post
      description: >-
        Creates a new post with text content. Can be a regular post, article, or
        other post type. Posts can be public, unlisted, followers-only, or
        direct messages. Sensitive content requires a content warning. The post
        is automatically distributed to followers and federated instances.
      tags:
        - Posts
      parameters:
        - description: Scope owner to resolve the post context
          required: false
          name: ownerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePost'
        required: true
      responses:
        '200':
          description: Post object just created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostsSensitiveContentWarning
                message: The sensitive flag must be set together with a content warning
          description: The sensitive flag must be set together with a content warning
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/posts/feeds/following:
    get:
      summary: Get home feed
      description: >-
        Returns the home feed showing posts from accounts the current user
        follows. This is the main timeline feed. Supports caching for
        performance, with fallback to database if cache is empty or
        regenerating. Can include follow status, bookmarks, and translations.
      tags:
        - Posts
      parameters:
        - description: Load from database
          required: false
          name: ignoreCache
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include bookmark field
          name: includeBookmarkStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include follow status
          name: includeFollowStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Filter posts by ownerType
          required: false
          name: ownerType
          in: query
          schema:
            $ref: '#/components/schemas/PostOwnerType'
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Include repostedBy. Default true
          name: withRepostedBy
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include translation
          name: withTranslation
          in: query
          schema:
            type: boolean
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/posts/feeds/public:
    get:
      summary: Get public posts feed
      description: >-
        Returns a feed of public posts visible to everyone. Can be filtered by
        owner type, local vs federated posts, and whether to include reposts.
        Supports various metadata inclusions like follow status, bookmarks,
        translations, and trends. Also called Discover Feed.
      tags:
        - Posts
      parameters:
        - description: Include bookmark field
          name: includeBookmarkStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include follow status
          name: includeFollowStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: List only local posts (if true). Remote only if false. Any if null
          name: local
          in: query
          schema:
            type: boolean
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Scope owner to resolve the post context
          required: false
          name: ownerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Filter posts by ownerType
          required: false
          name: ownerType
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/PostOwnerType'
            nullable: true
        - description: If false - force showing reposts
          name: skipReposts
          in: query
          schema:
            type: boolean
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Include repostedBy. Default true
          name: withRepostedBy
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include translation
          name: withTranslation
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include trends
          name: withTrends
          in: query
          schema:
            type: boolean
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostsNoOwnerType
                message: An ownerType must be provided
          description: An ownerType must be provided
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ForumNotFound:
                  description: The specified forum not found
                  value:
                    errorCode: ForumNotFound
                    message: The specified forum not found
                CategoryNotFound:
                  description: The specified category not found
                  value:
                    errorCode: CategoryNotFound
                    message: The specified category not found
                EventNotFound:
                  description: The specified event not found
                  value:
                    errorCode: EventNotFound
                    message: The specified event not found
          description: Not Found
      security:
        - header: []
  /api/v1/posts/following:
    get:
      summary: Get home feed
      description: >-
        Returns the home feed showing posts from accounts the current user
        follows. This is the main timeline feed. Supports caching for
        performance, with fallback to database if cache is empty or
        regenerating. Can include follow status, bookmarks, and translations.
      tags:
        - Posts
      parameters:
        - name: ignoreCache
          in: query
          schema:
            type: boolean
            nullable: true
        - name: includeBookmarkStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - name: includeFollowStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: ownerType
          in: query
          schema:
            $ref: '#/components/schemas/PostOwnerType'
          required: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: withRepostedBy
          in: query
          schema:
            type: boolean
            nullable: true
        - name: withTranslation
          in: query
          schema:
            type: boolean
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/posts/liked:
    get:
      summary: Get liked posts
      description: >-
        Returns all posts that the currently authenticated user has liked. Can
        be filtered by owner type to show only posts from users, groups,
        categories, or events.
      tags:
        - Posts
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Scope owner to resolve the post context
          required: false
          name: ownerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Filter posts by ownerType
          required: false
          name: ownerType
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/PostOwnerType'
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ForumNotFound:
                  description: The specified forum not found
                  value:
                    errorCode: ForumNotFound
                    message: The specified forum not found
                CategoryNotFound:
                  description: The specified category not found
                  value:
                    errorCode: CategoryNotFound
                    message: The specified category not found
                EventNotFound:
                  description: The specified event not found
                  value:
                    errorCode: EventNotFound
                    message: The specified event not found
          description: Not Found
      security:
        - header: []
  /api/v1/posts/markdown2html:
    put:
      summary: Convert markdown to HTML
      description: >-
        Converts markdown formatted text to HTML for preview purposes. Supports
        standard markdown syntax and returns properly formatted HTML. Useful for
        previewing how markdown content will appear when rendered in posts or
        articles.
      tags:
        - Posts
      requestBody:
        content:
          text/plain:
            schema:
              maxLength: 50000
              pattern: \S
              type: string
        required: true
      responses:
        '200':
          description: OK
          content:
            text/html:
              schema:
                type: string
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/posts/mentioned:
    get:
      summary: Get posts with mentions
      description: >-
        Returns all posts where the currently authenticated user was mentioned.
        Can be filtered by owner type and privacy level (e.g., to show only
        direct messages where mentioned).
      tags:
        - Posts
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Scope owner to resolve the post context
          required: false
          name: ownerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Filter posts by ownerType
          required: false
          name: ownerType
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/PostOwnerType'
            nullable: true
        - description: Filter posts by DIRECT only
          required: false
          name: private
          in: query
          schema:
            type: boolean
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ForumNotFound:
                  description: The specified forum not found
                  value:
                    errorCode: ForumNotFound
                    message: The specified forum not found
                CategoryNotFound:
                  description: The specified category not found
                  value:
                    errorCode: CategoryNotFound
                    message: The specified category not found
                EventNotFound:
                  description: The specified event not found
                  value:
                    errorCode: EventNotFound
                    message: The specified event not found
          description: Not Found
      security:
        - header: []
  /api/v1/posts/my:
    get:
      summary: Get current user's posts
      description: >-
        Returns all posts created by the currently authenticated user. Can
        filter for reposts only or bookmarked posts only. Optionally includes
        comments and bookmark status.
      tags:
        - Posts
      parameters:
        - description: Return bookmarked only
          required: false
          name: bookmarkedOnly
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include bookmark field
          required: false
          name: includeBookmarkStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include comments
          required: false
          name: includeComments
          in: query
          schema:
            type: boolean
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Scope owner to resolve the post context
          required: false
          name: ownerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Return reposts only
          required: false
          name: repostsOnly
          in: query
          schema:
            type: boolean
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ForumNotFound:
                  description: The specified forum not found
                  value:
                    errorCode: ForumNotFound
                    message: The specified forum not found
                CategoryNotFound:
                  description: The specified category not found
                  value:
                    errorCode: CategoryNotFound
                    message: The specified category not found
                EventNotFound:
                  description: The specified event not found
                  value:
                    errorCode: EventNotFound
                    message: The specified event not found
          description: Not Found
      security:
        - header: []
  /api/v1/posts/pins:
    get:
      summary: Get user's pinned posts
      description: >-
        Returns a list of all posts the authenticated user has pinned to their
        profile. Can optionally filter to show only top-level posts or include
        replies.
      tags:
        - Pins
      parameters:
        - description: Scope owner to resolve the post context
          required: false
          name: ownerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Returns top posts only or posts + replies
          required: false
          name: postOnly
          in: query
          schema:
            type: boolean
            nullable: true
      responses:
        '200':
          description: List of pinned posts ids
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeId'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ForumNotFound:
                  description: The specified forum not found
                  value:
                    errorCode: ForumNotFound
                    message: The specified forum not found
                CategoryNotFound:
                  description: The specified category not found
                  value:
                    errorCode: CategoryNotFound
                    message: The specified category not found
                EventNotFound:
                  description: The specified event not found
                  value:
                    errorCode: EventNotFound
                    message: The specified event not found
          description: Not Found
      security:
        - header: []
  /api/v1/posts/pins/{postId}:
    delete:
      summary: Unpin a post from profile
      description: Removes a previously pinned post from the authenticated user's profile.
      tags:
        - Pins
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                PostNotFound:
                  description: The specified post not found
                  value:
                    errorCode: PostNotFound
                    message: The specified post not found
                PostWasNotPinned:
                  description: The post was not pinned
                  value:
                    errorCode: PostWasNotPinned
                    message: The post was not pinned
          description: Not Found
      security:
        - header: []
    post:
      summary: Pin a post to profile
      description: >-
        Pins a post to the authenticated user's profile. Only own posts can be
        pinned, and there is a limit on the number of pinned posts. Direct
        messages and reposts cannot be pinned.
      tags:
        - Pins
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                RepostCantPin:
                  description: A repost cannot be pinned
                  value:
                    errorCode: RepostCantPin
                    message: A repost cannot be pinned
                OnlyOwnCanPin:
                  description: Only your own posts can be pinned
                  value:
                    errorCode: OnlyOwnCanPin
                    message: Only your own posts can be pinned
                DirectCantPin:
                  description: Direct posts can't be pinned
                  value:
                    errorCode: DirectCantPin
                    message: Direct posts can't be pinned
                PostPinLimit:
                  description: You have already pinned the maximum number of posts
                  value:
                    errorCode: PostPinLimit
                    message: You have already pinned the maximum number of posts
                NotGroupMember:
                  description: The user must be a member of the group
                  value:
                    errorCode: NotGroupMember
                    message: The user must be a member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostAlreadyPinned
                message: The post has already been pinned
          description: The post has already been pinned
      security:
        - header: []
  /api/v1/posts/public:
    get:
      summary: Get public posts feed
      description: >-
        Returns a feed of public posts visible to everyone. Can be filtered by
        owner type, local vs federated posts, and whether to include reposts.
        Supports various metadata inclusions like follow status, bookmarks,
        translations, and trends.
      tags:
        - Posts
      parameters:
        - name: includeBookmarkStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - name: includeFollowStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: local
          in: query
          schema:
            type: boolean
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: ownerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: ownerType
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/PostOwnerType'
            nullable: true
        - name: skipReposts
          in: query
          schema:
            type: boolean
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: withRepostedBy
          in: query
          schema:
            type: boolean
            nullable: true
        - name: withTranslation
          in: query
          schema:
            type: boolean
            nullable: true
        - name: withTrends
          in: query
          schema:
            type: boolean
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostsNoOwnerType
                message: An ownerType must be provided
          description: An ownerType must be provided
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ForumNotFound:
                  description: The specified forum not found
                  value:
                    errorCode: ForumNotFound
                    message: The specified forum not found
                CategoryNotFound:
                  description: The specified category not found
                  value:
                    errorCode: CategoryNotFound
                    message: The specified category not found
                EventNotFound:
                  description: The specified event not found
                  value:
                    errorCode: EventNotFound
                    message: The specified event not found
          description: Not Found
      security:
        - header: []
  /api/v1/posts/replies:
    get:
      summary: Get user's replies
      description: >-
        Returns posts that a user has replied to, along with their replies.
        Shows the original post as the parent with the user's reply nested
        within it. Useful for viewing a user's conversation participation.
      tags:
        - Posts
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Scope owner to resolve the post context
          required: false
          name: ownerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: List specific user's posts
          required: false
          name: userId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: List specific user's posts
          required: false
          name: username
          in: query
          schema:
            type: string
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostsRepliesAbsentParams
                message: The userId or username must be provided
          description: The userId or username must be provided
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ForumNotFound:
                  description: The specified forum not found
                  value:
                    errorCode: ForumNotFound
                    message: The specified forum not found
                CategoryNotFound:
                  description: The specified category not found
                  value:
                    errorCode: CategoryNotFound
                    message: The specified category not found
                EventNotFound:
                  description: The specified event not found
                  value:
                    errorCode: EventNotFound
                    message: The specified event not found
          description: Not Found
      security:
        - header: []
  /api/v1/posts/subscribe:
    get:
      tags:
        - Posts
      parameters:
        - description: Return all subscriptions
          required: false
          name: all
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Scope owner to resolve the post context
          required: false
          name: ownerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ForumNotFound:
                  description: The specified forum not found
                  value:
                    errorCode: ForumNotFound
                    message: The specified forum not found
                CategoryNotFound:
                  description: The specified category not found
                  value:
                    errorCode: CategoryNotFound
                    message: The specified category not found
                EventNotFound:
                  description: The specified event not found
                  value:
                    errorCode: EventNotFound
                    message: The specified event not found
          description: Not Found
      summary: Get Subscribes
      security:
        - header: []
  /api/v1/posts/{postId}:
    put:
      summary: Update post content
      description: >-
        Updates an existing post's content, privacy settings, or metadata. Only
        the post author can update their own posts. Cannot update comments
        through this endpoint. Sensitive content must include a content warning.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePost'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostsSensitiveContentWarning
                message: The sensitive flag must be set together with a content warning
          description: The sensitive flag must be set together with a content warning
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostsCantChangeOthersPost
                message: Cannot update another user's post
          description: Cannot update another user's post
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
      security:
        - header: []
    get:
      summary: Get post by ID
      description: >-
        Retrieves a specific post by its ID. Can optionally include comments
        with configurable depth levels, parent posts for comments, bookmarks,
        translations, trends, and repost information. Supports building comment
        trees with specified depth limits.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Include bookmark field
          required: false
          name: includeBookmarkStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Limit first level comment paging count
          required: false
          name: limitFirstLevelComments
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Limit second level comment paging count
          required: false
          name: limitSecondLevelComments
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Max comment level depth
          required: false
          name: maxLevel
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Min comment level depth
          required: false
          name: minLevel
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Load post with comments
          required: false
          name: withComments
          in: query
          schema:
            type: boolean
            nullable: true
        - description: |-
            If comment, load it with parents.
                           In such a case returns root with request `postId` comment inside replies
          required: false
          name: withParents
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include repostedBy. Default true
          name: withRepostedBy
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include translation
          required: false
          name: withTranslation
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include trends
          name: withTrends
          in: query
          schema:
            type: boolean
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
      security:
        - header: []
    delete:
      summary: Delete a post
      description: >-
        Permanently deletes a post. Only the post author can delete their own
        posts. This action removes the post from all timelines and sends
        deletion notifications to federated instances.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Post has been deleted successfully
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostsCantChangeOthersPost
                message: Cannot update another user's post
          description: Cannot update another user's post
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
      security:
        - header: []
  /api/v1/posts/{postId}/bookmark:
    delete:
      summary: Remove bookmark
      description: >-
        Removes a post from the authenticated user's bookmarks. Fails if the
        post was not previously bookmarked. This action is private and does not
        notify the post author.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                PostNotFound:
                  description: The specified post not found
                  value:
                    errorCode: PostNotFound
                    message: The specified post not found
                PostWasNotBookmarked:
                  description: The bookmark record not found
                  value:
                    errorCode: PostWasNotBookmarked
                    message: The bookmark record not found
          description: Not Found
      security:
        - header: []
    post:
      summary: Bookmark a post
      description: >-
        Adds a post to the authenticated user's bookmarks for later reading.
        Bookmarks are private and not visible to other users or the post author.
        Each post can only be bookmarked once per user.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostAlreadyBookmarked
                message: The post has already been bookmarked
          description: The post has already been bookmarked
      security:
        - header: []
  /api/v1/posts/{postId}/comments:
    get:
      summary: Get post comments
      description: >-
        Retrieves all comments for a specific post. Supports pagination and
        configurable comment depth levels. Returns an empty list if comments are
        disabled for the post. Comments are organized in a tree structure based
        on their reply relationships.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Limit first level comment paging count
          required: false
          name: limitFirstLevelComments
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: maxLevel
          in: query
          schema:
            format: int32
            maximum: 100
            minimum: 0
            type: integer
            nullable: true
        - name: minLevel
          in: query
          schema:
            format: int32
            maximum: 100
            minimum: 0
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
      security:
        - header: []
    post:
      summary: Create a comment
      description: >-
        Creates a new comment on a post. Comments can be nested replies to other
        comments. The authenticated user becomes the comment author. Comments
        inherit visibility from their parent post.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePost'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
      security:
        - header: []
  /api/v1/posts/{postId}/comments/{commentId}:
    put:
      summary: Update a comment
      description: >-
        Updates an existing comment's content. Only the comment author can
        update their own comments. The comment must belong to the specified
        post. Maintains the comment's position in the thread hierarchy.
      tags:
        - Posts
      parameters:
        - name: commentId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePost'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                PostsCantChangeOthersComment:
                  description: Cannot update another user's comment
                  value:
                    errorCode: PostsCantChangeOthersComment
                    message: Cannot update another user's comment
                PostsCommentForWrongPost:
                  description: The comment does not belong to the specified post
                  value:
                    errorCode: PostsCommentForWrongPost
                    message: The comment does not belong to the specified post
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                PostNotFound:
                  description: The specified post not found
                  value:
                    errorCode: PostNotFound
                    message: The specified post not found
                PostCommentNotFound:
                  description: The specified post comment not found
                  value:
                    errorCode: PostCommentNotFound
                    message: The specified post comment not found
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostCommentNoUpdated
                message: Failed to update the post comment
          description: Failed to update the post comment
      security:
        - header: []
    delete:
      summary: Delete a comment
      description: >-
        Permanently deletes a comment from a post. Only the comment author can
        delete their own comments. The comment must belong to the specified
        post. Child comments may be affected depending on the platform's
        threading model.
      tags:
        - Posts
      parameters:
        - name: commentId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Comment has been deleted successfully
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostsCommentForWrongPost
                message: The comment does not belong to the specified post
          description: The comment does not belong to the specified post
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                PostNotFound:
                  description: The specified post not found
                  value:
                    errorCode: PostNotFound
                    message: The specified post not found
                PostCommentNotFound:
                  description: The specified post comment not found
                  value:
                    errorCode: PostCommentNotFound
                    message: The specified post comment not found
          description: Not Found
      security:
        - header: []
  /api/v1/posts/{postId}/detach:
    post:
      summary: Detach repost from original
      description: >-
        Allows the original post author to detach a repost or quote from their
        post. This breaks the connection between the repost and the original,
        typically used when the repost violates the author's wishes or contains
        inappropriate commentary.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostsCannotDetach
                message: Cannot detach post. Please detach a repost or a quote
          description: Cannot detach post. Please detach a repost or a quote
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostsCantChangeOthersPost
                message: Cannot update another user's post
          description: Cannot update another user's post
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
      security:
        - header: []
  /api/v1/posts/{postId}/downvote:
    post:
      summary: Downvote a post
      description: Add a negative vote to a post
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: A summary of votes for the post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostVotesSummary'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
                NoVotingOnOwnPost:
                  description: Voting on own post is not allowed
                  value:
                    errorCode: NoVotingOnOwnPost
                    message: Voting on own post is not allowed
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
      security:
        - header: []
  /api/v1/posts/{postId}/edits:
    get:
      summary: View edit history of a post
      description: >-
        Retrieves the complete edit history of a post, showing all versions from
        creation to current state. Each edit includes the text, media, mentions,
        and timestamp of the change. Useful for transparency and tracking post
        modifications over time.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PostEdit'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
      security:
        - header: []
  /api/v1/posts/{postId}/likes:
    get:
      summary: Get post likes
      description: >-
        Returns a list of users who have liked a specific post. Can include
        follow relationship status between the viewer and the liking users.
        Supports pagination for posts with many likes.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Include followed status
          required: false
          name: includeFollowedStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include following status
          required: false
          name: includeFollowingStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PostActivity'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
      security:
        - header: []
    delete:
      summary: Unlike a post
      description: >-
        Removes the authenticated user's like from a post. Returns the new total
        number of likes. Sends unlike notifications and federates the activity.
        Fails if the post was not previously liked.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: New number of likes
          content:
            application/json:
              schema:
                type: integer
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                PostNotFound:
                  description: The specified post not found
                  value:
                    errorCode: PostNotFound
                    message: The specified post not found
                PostWasNotLiked:
                  description: The like record not found
                  value:
                    errorCode: PostWasNotLiked
                    message: The like record not found
          description: Not Found
      security:
        - header: []
    post:
      summary: Like a post
      description: >-
        Adds a like to a post from the authenticated user. Each user can only
        like a post once. Returns the new total number of likes. Sends like
        notifications to the post author and federates the activity.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: New number of likes
          content:
            application/json:
              schema:
                type: integer
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostAlreadyLiked
                message: The post has already been liked
          description: The post has already been liked
      security:
        - header: []
  /api/v1/posts/{postId}/refresh-card:
    post:
      summary: Refresh the preview card for a post
      description: >-
        Regenerates the link preview card for a post that contains URLs. Only
        the post author can refresh the card. This is useful when the linked
        content has changed and you want to update the preview information.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Updated card data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
                PostsCantChangeOthersPost:
                  description: Cannot update another user's post
                  value:
                    errorCode: PostsCantChangeOthersPost
                    message: Cannot update another user's post
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                PostNotFound:
                  description: The specified post not found
                  value:
                    errorCode: PostNotFound
                    message: The specified post not found
                LinkPreviewNotAvailable:
                  description: Link preview not available
                  value:
                    errorCode: LinkPreviewNotAvailable
                    message: Link preview not available
          description: Not Found
      security:
        - header: []
  /api/v1/posts/{postId}/repost:
    delete:
      summary: Undo a repost
      description: >-
        Removes your repost or quote of a specific post. This deletes the repost
        from your timeline and notifies the original author. Only your own
        reposts can be undone.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostsCantChangeOthersPost
                message: Cannot update another user's post
          description: Cannot update another user's post
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotReposted
                message: The post has not been reposted
          description: The post has not been reposted
      security:
        - header: []
    post:
      summary: Repost or quote another post
      description: >-
        Creates a repost (boost) or quote post of someone else's content.
        Regular reposts simply share the original post, while quotes add your
        own commentary. Only public posts and public follow-posts can be
        reposted. You cannot repost a repost.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      requestBody:
        description: >-
          Optional param, omit for repost or specify with 'text' to create a
          quote
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePost'
      responses:
        '200':
          description: Post object just created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostsCannotRepostRepost
                message: Cannot repost a repost. Please repost the original
          description: Cannot repost a repost. Please repost the original
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostsRepostPublicOnly
                message: Only public posts can be reposted
          description: Only public posts can be reposted
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
      security:
        - header: []
  /api/v1/posts/{postId}/reposts:
    get:
      summary: Get post reposts
      description: >-
        Returns a list of users who have reposted or quoted a specific post. Can
        filter by repost type (regular repost vs quote). Includes follow
        relationship status and supports deduplication of multiple reposts by
        the same user.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: Include followed status
          required: false
          name: includeFollowedStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include following status
          required: false
          name: includeFollowingStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - name: kind
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/RepostParam'
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: skipDuplicates
          in: query
          schema:
            type: boolean
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PostActivity'
      security:
        - header: []
  /api/v1/posts/{postId}/subscribe:
    post:
      summary: Subscribe to post notifications
      description: >-
        Subscribes the authenticated user to receive notifications for new
        activity on a post (new comments, edits, etc.). Users cannot subscribe
        to their own posts as they already receive notifications by default.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                PostAlreadySubscribed:
                  description: The post has already been subscribed to
                  value:
                    errorCode: PostAlreadySubscribed
                    message: The post has already been subscribed to
                SubscribeSelf:
                  description: Cannot subscribe to your own post
                  value:
                    errorCode: SubscribeSelf
                    message: Cannot subscribe to your own post
          description: Conflict
      security:
        - header: []
    delete:
      summary: Unsubscribe from post
      description: >-
        Removes the subscription for post notifications. The user will no longer
        receive notifications about new activity on this post. Does not affect
        notifications already received.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                PostNotFound:
                  description: The specified post not found
                  value:
                    errorCode: PostNotFound
                    message: The specified post not found
                PostWasNotSubscribed:
                  description: The subscription to post not found
                  value:
                    errorCode: PostWasNotSubscribed
                    message: The subscription to post not found
          description: Not Found
      security:
        - header: []
  /api/v1/posts/{postId}/track-view:
    post:
      summary: Track post view
      description: >-
        Records that a user has viewed this post. Used for analytics and
        engagement metrics. Works for both authenticated and unauthenticated
        users.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
      security:
        - header: []
  /api/v1/posts/{postId}/translate:
    post:
      summary: Translate post content
      description: >-
        Translates the text content of a post to the specified target language.
        Can return either plain text or HTML formatted translation. Uses
        automatic translation services to provide the translation.
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          schema:
            type: boolean
            nullable: true
        - name: lang
          in: query
          schema:
            $ref: '#/components/schemas/Language'
          required: true
      responses:
        '200':
          description: Post translation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostTranslation'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
      security:
        - header: []
  /api/v1/posts/{postId}/upvote:
    post:
      summary: Upvote a post
      description: Add a positive vote to a post
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: A summary of votes for the post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostVotesSummary'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                GroupNoPublicAccess:
                  description: >-
                    The group must be public or the requesting user must be a
                    member of the group
                  value:
                    errorCode: GroupNoPublicAccess
                    message: >-
                      The group must be public or the requesting user must be a
                      member of the group
                NoVotingOnOwnPost:
                  description: Voting on own post is not allowed
                  value:
                    errorCode: NoVotingOnOwnPost
                    message: Voting on own post is not allowed
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
      security:
        - header: []
  /api/v1/posts/{postId}/votes:
    get:
      summary: Get post votes
      description: Returns a summary of votes for a post
      tags:
        - Posts
      parameters:
        - name: postId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostVotesSummary'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: PostNotFound
                message: The specified post not found
          description: The specified post not found
      security:
        - header: []
  /api/v1/rbac:
    get:
      summary: Retrieves all RBAC-guarded resources and their access lists
      tags:
        - RBAC
      responses:
        '200':
          description: List of all RBAC-guarded resources and their access lists
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResourceModel'
      security: []
  /api/v1/rbac/actors/{actorId}/permissions:
    get:
      summary: Retrieves permissions for the specified actor within a scope
      description: |2-

                Retrieves all permissions assigned to an actor within a specified scope.
                If no scope is provided, assumes GlobalScope
            
      tags:
        - RBAC
      parameters:
        - description: ID of the actor
          example: us_01jvvsnzd8fzhbct9dfzmgn9nn
          required: true
          name: actorId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            Optional scope to filter permissions, if ommitted assumes
            GlobalScope
          example: System or gr_05hxcvk1hjexere4pvtrj0hggt
          required: false
          name: scope
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Actor's permissions within the specified scope
          content:
            application/json:
              example:
                AdminSettings:
                  - Read
                  - Manage
                AppData:
                  - Read
                  - Manage
                Data:
                  - Read
                  - Manage
                Roles:
                  - Read
                  - Assign
                  - Manage
                Users:
                  - Read
                  - Manage
                  - Moderate
                  - Impersonate
              schema:
                type: object
                additionalProperties:
                  type: object
      security:
        - header: []
  /api/v1/rbac/actors/{actorId}/roles:
    get:
      summary: Retrieves roles for the specified actor within the specified scope
      description: |2-

                    Retrieves all roles assigned to the specified actor within the specified scope.
                    If no scope is specified, assumes the GlobalScope

        RBAC: requires Roles.Read
      tags:
        - RBAC
      parameters:
        - description: ID of the actor
          example: us_01jvvsnzd8fzhbct9dfzmgn9nn
          required: true
          name: actorId
          in: path
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            Optional scope to filter roles, defaults to GlobalScope ('System')
            if omitted
          example: System or gr_05hxcvk1hjexere4pvtrj0hggt
          required: false
          name: scope
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Actor's roles within the specified scope
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RBACRole'
      security:
        - header: []
  /api/v1/rbac/roles/{roleId}:
    put:
      summary: Update the specified role
      tags:
        - RBAC
      parameters:
        - name: roleId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/RoleId'
      requestBody:
        description: Updated role details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RBACRoleTemplate'
        required: true
      responses:
        '200':
          description: Successfully updated role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RBACRole'
        '400':
          description: Bad Request
      security:
        - header: []
      description: 'RBAC: requires Roles.Manage'
  /api/v1/rbac/scopes/{scope}/roles:
    get:
      summary: Retrieves all roles defined within the specified scope
      tags:
        - RBAC
      parameters:
        - description: Scope to filter permissions, if omitted assumes GlobalScope
          example: System or gr_05hxcvk1hjexere4pvtrj0hggt
          required: true
          name: scope
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved scope roles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RBACRole'
      security: []
      description: 'RBAC: requires Roles.Read'
    post:
      summary: Create a new role within the specified scope
      description: >-
        Creates a new role with specified permissions within the specified
        scope.


        RBAC: requires Roles.Manage
      tags:
        - RBAC
      parameters:
        - description: Scope to filter permissions
          example: System or gr_05hxcvk1hjexere4pvtrj0hggt
          required: true
          name: scope
          in: path
          schema:
            type: string
      requestBody:
        description: Role details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RBACRoleTemplate'
        required: true
      responses:
        '200':
          description: The created role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RBACRole'
        '400':
          description: Bad Request
      security:
        - header: []
  /api/v1/rbac/scopes/{scope}/roles/{roleName}:
    delete:
      summary: Delete the specified role from the specified scope
      tags:
        - RBAC
      parameters:
        - description: The role's name to delete
          example: BOT
          required: true
          name: roleName
          in: path
          schema:
            type: string
        - description: Scope to filter permissions
          example: System or gr_05hxcvk1hjexere4pvtrj0hggt
          required: true
          name: scope
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Successfully deleted role
          content:
            application/json:
              schema: {}
      security:
        - header: []
      description: 'RBAC: requires Roles.Manage'
  /api/v1/rbac/{resource}:
    get:
      summary: Retrieves the description and the access list for the specified resource
      tags:
        - RBAC
      parameters:
        - description: The resource of interest
          example: GroupMembers
          required: true
          name: resource
          in: path
          schema:
            type: string
      responses:
        '200':
          description: The description and the access list for the specified resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceModel'
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security: []
  /api/v1/reports:
    post:
      summary: Report a post or a user to instance moderators
      tags:
        - Reports
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReport'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ConstraintViolation:
                  description: A request parameter constraint was violated
                  value:
                    errorCode: ConstraintViolation
                    message: A request parameter constraint was violated
                ReportPostsFromDifferentAuthors:
                  description: All reported posts should be from the same author
                  value:
                    errorCode: ReportPostsFromDifferentAuthors
                    message: All reported posts should be from the same author
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/rules:
    put:
      summary: Update existing rule
      description: |-
        Modifies an existing platform rule with updated text, hint, or ordering

        RBAC: requires Rules.Manage
      tags:
        - Rules
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Rule'
        required: true
      responses:
        '200':
          description: Updated Rule object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
        '400':
          description: Bad Request
      security: []
    get:
      summary: Get all rules
      description: Retrieves the complete list of platform rules that users must follow
      tags:
        - Rules
      responses:
        '200':
          description: List of all rules
          content:
            application/json:
              example:
                - text: >-
                    Mark any media with explicit sexual or violent content as
                    sensitive or incl...
                  hint: >-
                    This applies to provocative content even if specific body
                    parts aren't show...
                  order: 1000
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Rule'
      security: []
    post:
      summary: Create rules
      description: >-
        Creates a new platform rule with text content, hint explanation, and
        ordering priority


        RBAC: requires Rules.Manage
      tags:
        - Rules
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuleCreate'
        required: true
      responses:
        '200':
          description: Created Rule object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
        '400':
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/rules/reorder:
    post:
      summary: Reorder rules
      description: |-
        Updates the ordering of multiple rules at once

        RBAC: requires Rules.Manage
      tags:
        - Rules
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RuleOrderingRequest'
        required: true
      responses:
        '200':
          description: List of updated rules
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Rule'
        '400':
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security: []
  /api/v1/rules/{id}:
    delete:
      summary: Delete existing rule
      description: |-
        Permanently removes a platform rule by its ID

        RBAC: requires Rules.Manage
      tags:
        - Rules
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      security: []
  /api/v1/search:
    get:
      summary: Search across public post, users, tags. No auth required
      description: >-
        Performs a search query across different content types with support for
        URL resolution, username lookups, and various filtering options
      tags:
        - Search
      parameters:
        - description: Actor Type, one of Person, Group, Service. Default is Person
          required: false
          name: actorType
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/ActorType'
            nullable: true
        - description: Search only in fasp providers
          required: false
          name: fasp
          in: query
          schema:
            type: boolean
        - description: Search only in fasp providers, returning hydrated results
          required: false
          name: faspHydrated
          in: query
          schema:
            type: boolean
        - description: Only include specific types of results. Like posts, users, tags
          required: false
          name: filter
          in: query
          schema:
            uniqueItems: true
            type: array
            items:
              $ref: '#/components/schemas/SearchFilter'
            nullable: true
        - description: following/follower status. Default ACCEPTED
          required: false
          name: followStatus
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/FollowingStatus'
              - default: ACCEPTED
        - description: Only include accounts that follows the user
          required: false
          name: followers
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Only include accounts that the user is following
          required: false
          name: following
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Filter posts by groupId
          required: false
          name: groupId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Filter posts by ownerId
          required: false
          name: ownerId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Filter posts by ownerType
          required: false
          name: ownerType
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/PostOwnerType'
            nullable: true
        - description: Search query
          required: false
          name: q
          in: query
          schema:
            type: string
            nullable: true
        - description: Attempt to resolve remote users (WebFinger lookup)
          required: false
          name: resolve
          in: query
          schema:
            default: true
            type: boolean
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Load post with comments. Default false
          required: false
          name: withComments
          in: query
          schema:
            type: boolean
            nullable: true
        - description: If comment, load it with direct parent (in originalPost field)
          required: false
          name: withParent
          in: query
          schema:
            type: boolean
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: Search result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SearchQueryRequired
                message: A search query must be provided
          description: A search query must be provided
      security: []
  /api/v1/sessions/all:
    delete:
      summary: Deletes all account sessions except current
      tags:
        - Sessions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SessionDeleteFail
                message: Failed to delete session
          description: Failed to delete session
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/sessions/list:
    get:
      summary: Returns a list of all sessions
      tags:
        - Sessions
      responses:
        '200':
          description: Sessions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SessionInfo'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/sessions/revoke/all:
    put:
      summary: Revokes all account sessions except current
      tags:
        - Sessions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SessionDeleteFail
                message: Failed to delete session
          description: Failed to delete session
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/sessions/revoke/{sessionKey}:
    put:
      summary: Revokes a session
      tags:
        - Sessions
      parameters:
        - name: sessionKey
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                SessionRevokeCurrent:
                  description: Can't revoke current session
                  value:
                    errorCode: SessionRevokeCurrent
                    message: Can't revoke current session
                SessionRevokeFail:
                  description: Failed to revoke session
                  value:
                    errorCode: SessionRevokeFail
                    message: Failed to revoke session
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/sessions/{sessionKey}:
    delete:
      summary: Deletes a session
      tags:
        - Sessions
      parameters:
        - name: sessionKey
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SessionDeleteFail
                message: Failed to delete session
          description: Failed to delete session
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/settings:
    put:
      summary: Update platform settings
      description: >-
        Update multiple platform-wide settings in a single operation. Each
        setting must be provided as a complete object with all required fields.
        Partial updates are not supported to ensure system stability and prevent
        configuration errors.
      tags:
        - Platform Settings
      requestBody:
        description: >-
          settings objects to be updated. complete objects must be provided -
          partial updates are not allowed.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformSettings'
        required: true
      responses:
        '200':
          description: number of updated settings
          content:
            application/json:
              example:
                updated: 3
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                SettingsInvalidKeyProvided:
                  description: Unknown settings key(s) %s
                  value:
                    errorCode: SettingsInvalidKeyProvided
                    message: Unknown settings key(s) %s
                SettingsKeyNotProvided:
                  description: No settings keys were provided
                  value:
                    errorCode: SettingsKeyNotProvided
                    message: No settings keys were provided
                SettingsValuesNotProvided:
                  description: No settings values were provided
                  value:
                    errorCode: SettingsValuesNotProvided
                    message: No settings values were provided
                SettingsPartialUpdateNotAllowed:
                  description: 'Partial updates are not allowed: %s'
                  value:
                    errorCode: SettingsPartialUpdateNotAllowed
                    message: 'Partial updates are not allowed: %s'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsForbidden
                message: Access denied for settings
          description: Access denied for settings
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsNotUpdated
                message: Failed to update settings
          description: Failed to update settings
      security: []
    get:
      summary: Get platform settings
      description: >-
        Retrieve specific platform-wide settings by their keys. Returns a JSON
        object mapping setting names to their configured values. Some settings
        may be publicly accessible while others require administrative
        permissions.
      tags:
        - Platform Settings
      parameters:
        - description: >-
            Comma-separated list of platform setting keys to retrieve. Each key
            must correspond to a valid platform setting definition registered in
            the system.


            Available keys are:


            ```wellesley.access```


            ```wellesley.uploads.policy.audio```


            ```wellesley.admin.auth```


            ```wellesley.branding```


            ```wellesley.admin.captcha```


            ```wellesley.captcha```


            ```wellesley.confirmationCode```


            ```wellesley.uploads.policy.doc```


            ```wellesley.instance.domainBlocks```


            ```wellesley.uploads.policy.emoji```


            ```wellesley.uploads.policy.image```


            ```wellesley.instance.admin```


            ```wellesley.instance.contacts```


            ```wellesley.instance.legal```


            ```wellesley.admin.language```


            ```wellesley.admin.mediacache```


            ```wellesley.admin.openai```


            ```wellesley.posts```


            ```wellesley.registration```


            ```wellesley.admin.link_service```


            ```wellesley.admin.sms```


            ```wellesley.admin.sms.aws```


            ```wellesley.admin.sms.sinch```


            ```wellesley.admin.sms.twilio```


            ```wellesley.translation```


            ```wellesley.admin.translation```


            ```wellesley.admin.uploads```


            ```wellesley.username.release```


            ```wellesley.uploads.policy.video```
          name: keys
          required: true
          in: query
          schema:
            type: array
            items:
              type: string
          example: wellesley.access,wellesley.uploads.policy.audio
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/PlatformSettings'
          description: Response PlatformSettings
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                SettingsInvalidKeyProvided:
                  description: Unknown settings key(s) %s
                  value:
                    errorCode: SettingsInvalidKeyProvided
                    message: Unknown settings key(s) %s
                SettingsKeyNotProvided:
                  description: No settings keys were provided
                  value:
                    errorCode: SettingsKeyNotProvided
                    message: No settings keys were provided
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsForbidden
                message: Access denied for settings
          description: Access denied for settings
      security: []
    delete:
      summary: Delete platform settings
      description: >-
        Remove specific platform settings by their keys. This operation will
        permanently delete the specified settings and revert them to their
        system default values. Use extreme caution as this affects the entire
        platform.
      tags:
        - Platform Settings
      parameters:
        - description: >-
            Comma-separated list of platform setting keys to delete. Each key
            must correspond to a valid platform setting that exists and can be
            safely removed.


            Available keys are:


            ```wellesley.access```


            ```wellesley.uploads.policy.audio```


            ```wellesley.admin.auth```


            ```wellesley.branding```


            ```wellesley.admin.captcha```


            ```wellesley.captcha```


            ```wellesley.confirmationCode```


            ```wellesley.uploads.policy.doc```


            ```wellesley.instance.domainBlocks```


            ```wellesley.uploads.policy.emoji```


            ```wellesley.uploads.policy.image```


            ```wellesley.instance.admin```


            ```wellesley.instance.contacts```


            ```wellesley.instance.legal```


            ```wellesley.admin.language```


            ```wellesley.admin.mediacache```


            ```wellesley.admin.openai```


            ```wellesley.posts```


            ```wellesley.registration```


            ```wellesley.admin.link_service```


            ```wellesley.admin.sms```


            ```wellesley.admin.sms.aws```


            ```wellesley.admin.sms.sinch```


            ```wellesley.admin.sms.twilio```


            ```wellesley.translation```


            ```wellesley.admin.translation```


            ```wellesley.admin.uploads```


            ```wellesley.username.release```


            ```wellesley.uploads.policy.video```
          name: keys
          required: true
          in: query
          schema:
            type: array
            items:
              type: string
          example: wellesley.access,wellesley.uploads.policy.audio
      responses:
        '200':
          description: number of deleted settings
          content:
            application/json:
              example:
                deleted: 3
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                SettingsKeyNotProvided:
                  description: No settings keys were provided
                  value:
                    errorCode: SettingsKeyNotProvided
                    message: No settings keys were provided
                SettingsInvalidKeyProvided:
                  description: Unknown settings key(s) %s
                  value:
                    errorCode: SettingsInvalidKeyProvided
                    message: Unknown settings key(s) %s
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsForbidden
                message: Access denied for settings
          description: Access denied for settings
      security: []
  /api/v1/settings/names:
    get:
      summary: List setting keys
      description: >-
        Return a list of fully-qualified setting key names for the requested
        settings type.
      tags:
        - Platform Settings
      parameters:
        - description: >-
            Namespace to list keys for. One of: Platform, User, Group,
            GroupMember.
          name: type
          required: true
          in: query
          schema:
            $ref: '#/components/schemas/Namespace'
      responses:
        '200':
          description: Array of setting key names
          content:
            application/json:
              schema: {}
      security: []
  /api/v1/settings/user:
    put:
      summary: Update user settings
      description: >-
        Update multiple user settings in a single operation for the
        authenticated user. Each setting must be provided as a complete object
        with all required fields. Partial updates are not supported to ensure
        data consistency and prevent preference corruption.
      tags:
        - User Settings
      requestBody:
        description: >-
          settings objects to be updated. complete objects must be provided -
          partial updates are not allowed.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSettings'
        required: true
      responses:
        '200':
          description: number of updated settings
          content:
            application/json:
              example:
                updated: 3
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                SettingsInvalidKeyProvided:
                  description: Unknown settings key(s) %s
                  value:
                    errorCode: SettingsInvalidKeyProvided
                    message: Unknown settings key(s) %s
                SettingsKeyNotProvided:
                  description: No settings keys were provided
                  value:
                    errorCode: SettingsKeyNotProvided
                    message: No settings keys were provided
                SettingsValuesNotProvided:
                  description: No settings values were provided
                  value:
                    errorCode: SettingsValuesNotProvided
                    message: No settings values were provided
                SettingsPartialUpdateNotAllowed:
                  description: 'Partial updates are not allowed: %s'
                  value:
                    errorCode: SettingsPartialUpdateNotAllowed
                    message: 'Partial updates are not allowed: %s'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsForbidden
                message: Access denied for settings
          description: Access denied for settings
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsNotUpdated
                message: Failed to update settings
          description: Failed to update settings
      security:
        - header: []
    get:
      summary: Get user settings
      description: >-
        Retrieve specific user settings by their keys for the authenticated
        user. Returns a JSON object mapping setting names to their configured
        values. Only settings belonging to the current user are accessible
        through this endpoint.
      tags:
        - User Settings
      parameters:
        - description: >-
            Comma-separated list of user setting keys to retrieve. Each key must
            correspond to a valid user setting definition registered in the
            system.


            Available keys are:


            ```user.follow```


            ```user.notifications.policy```


            ```user.notifications.prefs```


            ```user.privacy```


            ```user.translation```
          name: keys
          required: true
          in: query
          schema:
            type: array
            items:
              type: string
          example: user.follow,user.notifications.policy
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/UserSettings'
          description: Response UserSettings
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                SettingsInvalidKeyProvided:
                  description: Unknown settings key(s) %s
                  value:
                    errorCode: SettingsInvalidKeyProvided
                    message: Unknown settings key(s) %s
                SettingsKeyNotProvided:
                  description: No settings keys were provided
                  value:
                    errorCode: SettingsKeyNotProvided
                    message: No settings keys were provided
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsForbidden
                message: Access denied for settings
          description: Access denied for settings
      security:
        - header: []
    delete:
      summary: Delete user settings
      description: >-
        Remove specific user settings by their keys for the authenticated user.
        This operation will permanently delete the specified settings and revert
        them to their default values. Deleted preferences cannot be recovered.
      tags:
        - User Settings
      parameters:
        - description: >-
            Comma-separated list of user setting keys to delete. Each key must
            correspond to a valid user setting that exists for the authenticated
            user.


            Available keys are:


            ```user.follow```


            ```user.notifications.policy```


            ```user.notifications.prefs```


            ```user.privacy```


            ```user.translation```
          name: keys
          required: true
          in: query
          schema:
            type: array
            items:
              type: string
          example: user.follow,user.notifications.policy
      responses:
        '200':
          description: number of deleted settings
          content:
            application/json:
              example:
                deleted: 3
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                SettingsKeyNotProvided:
                  description: No settings keys were provided
                  value:
                    errorCode: SettingsKeyNotProvided
                    message: No settings keys were provided
                SettingsInvalidKeyProvided:
                  description: Unknown settings key(s) %s
                  value:
                    errorCode: SettingsInvalidKeyProvided
                    message: Unknown settings key(s) %s
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: SettingsForbidden
                message: Access denied for settings
          description: Access denied for settings
      security:
        - header: []
  /api/v1/tags/featured:
    get:
      summary: Get list of featured tags
      tags:
        - Tags
      parameters:
        - description: List specific user's featured tags
          required: false
          name: userId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tag'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/tags/featured/{name}:
    delete:
      summary: Remove from featured tags by name
      tags:
        - Tags
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TagNotFound
                message: The specified tag not found
          description: The specified tag not found
      security:
        - header: []
    post:
      summary: Feature tag by name
      tags:
        - Tags
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TagFeaturingError
                message: Failed to feature the specified tag
          description: Failed to feature the specified tag
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/tags/follow/{name}:
    post:
      summary: Follow tag by name
      tags:
        - Tags
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TagFollowingError
                message: Failed to follow the specified tag
          description: Failed to follow the specified tag
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TagNotFound
                message: The specified tag not found
          description: The specified tag not found
      security:
        - header: []
  /api/v1/tags/followed:
    get:
      summary: Get list of followed tags
      tags:
        - Tags
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tag'
      security:
        - header: []
  /api/v1/tags/list:
    put:
      summary: Overwrite black/whitelist
      description: |-
        Bulk overwrite list entries for a scope

        RBAC:
        - requires ANY of Data.Manage, GroupData.Manage
      tags:
        - Tags v2
      parameters:
        - description: Scope id
          required: true
          name: scope
          in: query
          schema:
            type: string
        - description: Soft flag (blacklist only)
          required: false
          name: soft
          in: query
          schema:
            type: boolean
            nullable: true
        - description: List type
          required: true
          name: type
          in: query
          schema:
            $ref: '#/components/schemas/TagPolicyMode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
      security: []
    patch:
      summary: Add to black/whitelist
      description: |-
        Add entries. For blacklist, soft flag toggles hard/soft.

        RBAC:
        - requires ANY of Data.Manage, GroupData.Manage
      tags:
        - Tags v2
      parameters:
        - description: Scope id
          required: true
          name: scope
          in: query
          schema:
            type: string
        - description: Soft flag (blacklist only)
          required: false
          name: soft
          in: query
          schema:
            type: boolean
            nullable: true
        - description: List type
          required: true
          name: type
          in: query
          schema:
            $ref: '#/components/schemas/TagPolicyMode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      security: []
    get:
      summary: Get black/whitelist for a scope
      description: >-
        Returns array of tag names in black/whitelist. 'soft' applies only to
        blacklist.


        RBAC:

        - requires ANY of Data.Read, GroupData.Manage
      tags:
        - Tags v2
      parameters:
        - description: Scope id
          required: true
          name: scope
          in: query
          schema:
            type: string
        - description: Soft flag (blacklist only)
          required: false
          name: soft
          in: query
          schema:
            type: boolean
            nullable: true
        - description: List type
          required: true
          name: type
          in: query
          schema:
            $ref: '#/components/schemas/TagPolicyMode'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
      security: []
    delete:
      summary: Remove from black/whitelist
      description: >-
        Remove entries. For blacklist, soft must be specified to remove from
        that list.


        RBAC:

        - requires ANY of Data.Manage, GroupData.Manage
      tags:
        - Tags v2
      parameters:
        - description: Scope id
          required: true
          name: scope
          in: query
          schema:
            type: string
        - description: Soft flag (blacklist only)
          required: false
          name: soft
          in: query
          schema:
            type: boolean
            nullable: true
        - description: List type
          required: true
          name: type
          in: query
          schema:
            $ref: '#/components/schemas/TagPolicyMode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      security: []
  /api/v1/tags/policy:
    put:
      summary: Set policy mode
      description: |-
        Set scope policy to 'whitelist' or 'blacklist'.

        RBAC:
        - requires ANY of Data.Manage, GroupData.Manage
      tags:
        - Tags v2
      parameters:
        - name: scope
          in: query
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagPolicyMode'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      security: []
    get:
      summary: Get policy mode
      description: >-
        Returns 'whitelist' or 'blacklist' for scope. Defaults to 'blacklist' if
        unset.


        RBAC:

        - requires ANY of Data.Read, GroupData.Manage
      tags:
        - Tags v2
      parameters:
        - name: scope
          in: query
          schema:
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagPolicyMode'
      security: []
  /api/v1/tags/report:
    post:
      summary: Report a tag
      description: Creates a tag report in a scope.
      tags:
        - Tags v2
      parameters:
        - description: Canonical tag name
          required: true
          name: name
          in: query
          schema:
            type: string
        - description: Scope id
          required: true
          name: scope
          in: query
          schema:
            type: string
      requestBody:
        content:
          text/plain:
            schema:
              type: string
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      security:
        - header: []
  /api/v1/tags/reports:
    get:
      summary: List tag reports in a scope
      tags:
        - Tags v2
      parameters:
        - name: scope
          in: query
          schema:
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json: {}
      security: []
      description: |-
        RBAC:
        - requires ANY of Data.Read, GroupData.Manage
  /api/v1/tags/search:
    get:
      summary: Search tags by prefix
      description: Returns tag names matching partial name. Scope is optional.
      tags:
        - Tags v2
      parameters:
        - description: Max results
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Partial tag name
          required: true
          name: name
          in: query
          schema:
            type: string
        - description: Offset
          required: false
          name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: 'Scope id: ''global'' or TypeId'
          required: false
          name: scope
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
      security: []
  /api/v1/tags/trending:
    get:
      tags:
        - Tags
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tag'
      summary: Trending
      security: []
  /api/v1/tags/unfollow/{name}:
    post:
      summary: Unfollow tag by name
      tags:
        - Tags
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TagUnFollowingError
                message: Failed to unfollow the specified tag
          description: Failed to unfollow the specified tag
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TagNotFound
                message: The specified tag not found
          description: The specified tag not found
      security:
        - header: []
  /api/v1/tags/{name}:
    get:
      summary: Get tag by name
      tags:
        - Tags
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
        - description: Filter history since. 2 weeks by default
          required: false
          name: historySince
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/LocalDate'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: TagNotFound
                message: The specified tag not found
          description: The specified tag not found
      security: []
  /api/v1/translate/text:
    post:
      tags:
        - Translation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranslationRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslationResponse'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      summary: Translate
      security:
        - header: []
  /api/v1/trends/links:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Card'
      summary: Links
      tags:
        - Trends Resource
      security: []
  /api/v1/trends/posts:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
      summary: Posts
      tags:
        - Trends Resource
      security: []
      parameters:
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
  /api/v1/trends/tags:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tag'
      summary: Tags
      tags:
        - Trends Resource
      security: []
  /api/v1/uploads:
    post:
      summary: Create upload
      description: Create upload based on input data
      tags:
        - Uploads
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUpload'
        required: true
      responses:
        '200':
          description: Upload successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUploadResult'
        '400':
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security:
        - header: []
  /api/v1/uploads/batch:
    post:
      summary: Delete multiple uploads by id
      description: Delete multiple upload by id
      tags:
        - Uploads
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/TypeId'
        required: true
      responses:
        '200':
          description: Delete multiple upload is successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TypeId'
        '400':
          description: >-
            Bad request. All uploads should belong to the same uses and be less
            than 20
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UploadNotFound
                message: Upload not found
          description: Upload not found
      security:
        - header: []
  /api/v1/uploads/list:
    post:
      summary: List uploads based on input data
      description: List uploads based on input data
      tags:
        - Uploads
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadList'
        required: true
      responses:
        '200':
          description: Operation is successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Upload'
        '400':
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security:
        - header: []
  /api/v1/uploads/search:
    get:
      summary: Search uploads based on input data
      tags:
        - Uploads
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: Search uploads by a tag
          required: false
          name: tag
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/UploadsTags'
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - description: Search uploads by upload type
          required: false
          name: uploadType
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/UploadType'
            nullable: true
      responses:
        '200':
          description: Operation is successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUploadsResult'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: InvalidUploadListRequest
                message: >-
                  Invalid request to list uploads. Provide a valid userId,
                  pagination, and a supported order field (createdAt or size).
          description: >-
            Invalid request to list uploads. Provide a valid userId, pagination,
            and a supported order field (createdAt or size).
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security:
        - header: []
  /api/v1/uploads/usages:
    get:
      summary: Get posts, avatars and headers for specified upload ids
      tags:
        - Uploads
      parameters:
        - name: ids
          in: query
          schema:
            type: array
            items:
              type: string
            nullable: true
      responses:
        '200':
          description: Json with usages for specified upload ids
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadUsages'
        '400':
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
      security:
        - header: []
  /api/v1/uploads/{id}:
    get:
      summary: Get upload by id
      description: Gets upload by id
      tags:
        - Uploads
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Gets upload data with file info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        '400':
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UploadNotFound
                message: Upload not found
          description: Upload not found
      security:
        - header: []
    delete:
      summary: Delete upload by id
      description: Delete upload by id
      tags:
        - Uploads
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: Delete upload is successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteUploadResponse'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UploadNotFound
                message: Upload not found
          description: Upload not found
      security:
        - header: []
  /api/v1/uploads/{id}/meta:
    post:
      summary: Rewrite upload meta with new data
      description: Rewrite upload meta with new data
      tags:
        - Uploads
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: {}
        required: true
      responses:
        '200':
          description: Operation is successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        '400':
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UploadNotFound
                message: Upload not found
          description: Upload not found
      security:
        - header: []
    put:
      summary: Patch upload meta with data
      description: Patch upload meta with new data
      tags:
        - Uploads
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: {}
        required: true
      responses:
        '200':
          description: Operation is successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        '400':
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UploadNotFound
                message: Upload not found
          description: Upload not found
      security:
        - header: []
  /api/v1/uploads/{id}/privacy:
    post:
      summary: Rewrite upload privacy settings
      description: Rewrite upload privacy settings
      tags:
        - Uploads
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUploadPrivacy'
        required: true
      responses:
        '200':
          description: Operation is successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        '400':
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UploadNotFound
                message: Upload not found
          description: Upload not found
      security:
        - header: []
  /api/v1/uploads/{id}/tags:
    post:
      summary: Rewrite upload tags with new data
      description: Rewrite upload tags with new data
      tags:
        - Uploads
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UploadsTags'
        required: true
      responses:
        '200':
          description: Operation is successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        '400':
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UploadNotFound
                message: Upload not found
          description: Upload not found
      security:
        - header: []
    put:
      summary: Patch upload tags with data
      description: Patch upload tags with new data
      tags:
        - Uploads
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UploadsTags'
        required: true
      responses:
        '200':
          description: Operation is successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        '400':
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UploadNotFound
                message: Upload not found
          description: Upload not found
      security:
        - header: []
  /api/v1/uploads/{id}/thumbnail:
    post:
      summary: This route is responsible for updating video preview
      description: |2-

                    To update upload video preview you should specify exactly
                     the second of the video you want to create preview from
                
      tags:
        - Uploads
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeVideoThumbnail'
        required: true
      responses:
        '200':
          description: Operation is successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        '400':
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UploadNotFound
                message: Upload not found
          description: Upload not found
      security:
        - header: []
  /api/v1/user-alias:
    get:
      summary: List of aliases
      tags:
        - Aliases
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: array
                items:
                  type: string
      security:
        - header: []
    delete:
      summary: Remove alias
      tags:
        - Aliases
      parameters:
        - name: uri
          in: query
          schema:
            pattern: \S
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UserNotFound:
                  description: User not found
                  value:
                    errorCode: UserNotFound
                    message: User not found
                AliasNotFound:
                  description: Alias not found
                  value:
                    errorCode: AliasNotFound
                    message: Alias not found
          description: Not Found
      security:
        - header: []
    post:
      summary: Create alias
      tags:
        - Aliases
      parameters:
        - name: acct
          in: query
          schema:
            pattern: \S
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthForbidden
                message: Admin privileges are required
          description: Admin privileges are required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AliasAlreadyExists
                message: Alias already exists
          description: Alias already exists
      security:
        - header: []
  /api/v1/user-domain-block:
    get:
      summary: List of blocked domains for the user
      tags:
        - Domain-blocks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/user-domain-block/{domain}:
    delete:
      summary: Unblock previously blocked domain
      tags:
        - Domain-blocks
      parameters:
        - name: domain
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: DomainIsNotBlocked
                message: The domain is not currently blocked
          description: The domain is not currently blocked
      security:
        - header: []
    post:
      summary: Block specific domain
      description: |2-

                    Block a domain to:
                    * hide all public posts from it
                    * hide all notifications from it
                    * remove all followers from it
                    * prevent following new users from it (but does not remove existing follows)
                
      tags:
        - Domain-blocks
      parameters:
        - name: domain
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: DomainRequired
                message: A domain must be provided
          description: A domain must be provided
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: DomainAlreadyBlocked
                message: The domain is already blocked
          description: The domain is already blocked
      security:
        - header: []
  /api/v1/users:
    delete:
      summary: Delete user
      tags:
        - Users
      parameters:
        - name: id
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: name
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: User deleted
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserIdOrUserNameMissing
                message: The userId or userName must be provided
          description: The userId or userName must be provided
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: CantDeleteOtherUser
                message: Cannot delete a user from another account
          description: Cannot delete a user from another account
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security:
        - header: []
    post:
      summary: Create new user for the account
      description: 'User''s profile required fields: username, displayName, applicationId'
      tags:
        - Users
      requestBody:
        description: Json object with the users data
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/UserFull'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                AuthForbidden:
                  description: Admin privileges are required
                  value:
                    errorCode: AuthForbidden
                    message: Admin privileges are required
                CantAddOtherUser:
                  description: Cannot add a user to another account
                  value:
                    errorCode: CantAddOtherUser
                    message: Cannot add a user to another account
                OnlyAdminsCreateAdmin:
                  description: Only administrators can create admin users
                  value:
                    errorCode: OnlyAdminsCreateAdmin
                    message: Only administrators can create admin users
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AccountNotFound
                message: Account not found
          description: Account not found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                UserNameExists:
                  description: The username is already in use
                  value:
                    errorCode: UserNameExists
                    message: The username is already in use
                UserNameIsReserved:
                  description: The username is reserved and cannot be used
                  value:
                    errorCode: UserNameIsReserved
                    message: The username is reserved and cannot be used
          description: Conflict
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserCreationError
                message: Failed to create the user
          description: Failed to create the user
      security:
        - header: []
      parameters:
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
    get:
      summary: Get user by username
      tags:
        - Users
      parameters:
        - description: >-
            If true return also summary, stats, header and fields. Default
            false.
          required: false
          name: full
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include blocked_by status (target blocked viewer)
          required: false
          name: includeBlockedByStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include blocked status (viewer blocked target)
          required: false
          name: includeBlockedStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include followed status
          required: false
          name: includeFollowedStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include following status
          required: false
          name: includeFollowingStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include muted status
          required: false
          name: includeMutedStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: >-
            Include all relationship statuses (following, followed, blocked,
            blocked_by, muted)
          required: false
          name: relations
          in: query
          schema:
            type: boolean
            nullable: true
        - name: username
          in: query
          schema:
            pattern: \S
            type: string
          required: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/User'
                  - $ref: '#/components/schemas/UserFull'
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security: []
  /api/v1/users/check:
    get:
      summary: Check if username is already taken
      tags:
        - Users
      parameters:
        - name: username
          in: query
          schema:
            pattern: \S
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsernameCheck'
      security: []
  /api/v1/users/connections:
    get:
      summary: List mutual connections
      description: >-
        Returns users who have a mutual (bidirectional) follow relationship with
        the authenticated user. Both users follow each other. Can filter by
        connection status. By default returns only ACCEPTED mutual connections.
        Useful for finding close connections or friends.
      tags:
        - Follow
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: 'The target Follow status like: ACCEPTED/REJECTED/PENDING'
          required: false
          name: status
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/FollowingStatus'
              - default: ACCEPTED
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/users/follow/{username}:
    post:
      summary: Follow a user
      description: >-
        Initiates a follow relationship with a local or remote user. For remote
        users, specify the domain parameter or include it in the username
        (user@domain). Supports mutual follows (bidirectional connections) when
        mutual=true. Checks for blocks and self-follows. Remote follows are sent
        via ActivityPub. Local follows may auto-accept based on user settings.
      tags:
        - Follow
      parameters:
        - description: Username of the followee
          required: true
          name: username
          in: path
          schema:
            type: string
        - description: Followee's domain.  If omitted assumed to be local
          required: false
          name: domain
          in: query
          schema:
            type: string
            nullable: true
        - description: '''false'' for regular Follow, ''true'' for bidirectional Connect'
          required: false
          name: mutual
          in: query
          schema:
            default: false
            type: boolean
        - description: http vs. https.  For testing ONLY
          required: false
          name: scheme
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/AppScheme'
              - default: https
      responses:
        '200':
          description: Follow result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FollowResult'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                FolloweeDomainWithUnknownSoft:
                  description: Unknown ActivityPub software for the followee's domain
                  value:
                    errorCode: FolloweeDomainWithUnknownSoft
                    message: Unknown ActivityPub software for the followee's domain
                FollowersCantFollowSelf:
                  description: A user cannot follow themselves
                  value:
                    errorCode: FollowersCantFollowSelf
                    message: A user cannot follow themselves
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                FolloweeBlockFollower:
                  description: The followee has blocked the follower
                  value:
                    errorCode: FolloweeBlockFollower
                    message: The followee has blocked the follower
                FollowerBlockFollowee:
                  description: The follower has blocked the followee
                  value:
                    errorCode: FollowerBlockFollowee
                    message: The follower has blocked the followee
                FollowerBlockFolloweeDomain:
                  description: The follower has blocked the followee's domain
                  value:
                    errorCode: FollowerBlockFolloweeDomain
                    message: The follower has blocked the followee's domain
                FolloweeBlockFollowerDomain:
                  description: The followee has blocked the follower's domain
                  value:
                    errorCode: FolloweeBlockFollowerDomain
                    message: The followee has blocked the follower's domain
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: FolloweeNotFound
                message: The followee could not be found
          description: The followee could not be found
        '409':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: FollowersConflict
                message: A conflict occurred with the followers
          description: A conflict occurred with the followers
      security:
        - header: []
  /api/v1/users/follow/{username}/accept:
    post:
      summary: Accept follow request
      description: >-
        Accepts a pending follow request from another user. Changes follow
        status from PENDING to ACCEPTED. Checks for blocks before accepting.
        Sends Accept activity to remote followers via ActivityPub. Only the
        followee can accept their own follow requests.
      tags:
        - Follow
      parameters:
        - description: The URI of the prospective follower
          required: true
          name: username
          in: path
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: FollowWrongStatus
                message: The target status is invalid
          description: The target status is invalid
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                FolloweeBlockFollower:
                  description: The followee has blocked the follower
                  value:
                    errorCode: FolloweeBlockFollower
                    message: The followee has blocked the follower
                FollowerBlockFollowee:
                  description: The follower has blocked the followee
                  value:
                    errorCode: FollowerBlockFollowee
                    message: The follower has blocked the followee
                FolloweeBlockFollowerDomain:
                  description: The followee has blocked the follower's domain
                  value:
                    errorCode: FolloweeBlockFollowerDomain
                    message: The followee has blocked the follower's domain
                FollowerBlockFolloweeDomain:
                  description: The follower has blocked the followee's domain
                  value:
                    errorCode: FollowerBlockFolloweeDomain
                    message: The follower has blocked the followee's domain
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: FollowerNotFound
                message: The follower could not be found
          description: The follower could not be found
      security:
        - header: []
  /api/v1/users/follow/{username}/pend:
    post:
      summary: Reset follow request to pending
      description: >-
        Resets a previously accepted or rejected follow request back to PENDING
        status. Useful when reconsidering a follow decision. The request can
        then be accepted or rejected again. Only affects the local follow
        status, not remote ActivityPub state.
      tags:
        - Follow
      parameters:
        - description: The URI of the prospective follower
          required: true
          name: username
          in: path
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: FollowWrongStatus
                message: The target status is invalid
          description: The target status is invalid
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: FollowerNotFound
                message: The follower could not be found
          description: The follower could not be found
      security:
        - header: []
  /api/v1/users/follow/{username}/reject:
    post:
      summary: Reject follow request
      description: >-
        Rejects a pending follow request from another user. Changes follow
        status from PENDING to REJECTED. Sends Reject activity to remote
        followers via ActivityPub. The follower can retry following after
        rejection. Only the followee can reject their own follow requests.
      tags:
        - Follow
      parameters:
        - description: The URI of the prospective follower
          required: true
          name: username
          in: path
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: FollowWrongStatus
                message: The target status is invalid
          description: The target status is invalid
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: FollowerNotFound
                message: The follower could not be found
          description: The follower could not be found
      security:
        - header: []
  /api/v1/users/follow/{username}/undo:
    post:
      summary: Unfollow a user
      description: >-
        Removes a follow relationship with a local or remote user. For remote
        users, specify the domain parameter or include it in the username. If
        mutual=true, removes bidirectional connection. Sends Undo Follow
        activity to remote users via ActivityPub. Returns error if no follow
        relationship exists.
      tags:
        - Follow
      parameters:
        - description: Username of the followee
          required: true
          name: username
          in: path
          schema:
            type: string
        - description: Followee's domain.  If omitted assumed to be local
          required: false
          name: domain
          in: query
          schema:
            type: string
            nullable: true
        - description: '''false'' for regular Follow, ''true'' for bidirectional Connect'
          required: false
          name: mutual
          in: query
          schema:
            default: false
            type: boolean
        - description: http vs. https.  For testing ONLY
          required: false
          name: scheme
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/AppScheme'
              - default: https
      responses:
        '200':
          description: Follow result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FollowResult'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                FollowRecordNotFound:
                  description: The specified follow record not found
                  value:
                    errorCode: FollowRecordNotFound
                    message: The specified follow record not found
                FolloweeNotFound:
                  description: The followee could not be found
                  value:
                    errorCode: FolloweeNotFound
                    message: The followee could not be found
          description: Not Found
      security:
        - header: []
  /api/v1/users/followees:
    get:
      summary: List users you follow
      description: >-
        Returns a paginated list of users that the authenticated user follows.
        Can filter by follow status (ACCEPTED, PENDING, REJECTED) or return all
        statuses. By default returns only ACCEPTED followees. Includes both
        local and remote users.
      tags:
        - Follow
      parameters:
        - name: anyStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: 'The target Follow status like: ACCEPTED/REJECTED/PENDING'
          required: false
          name: status
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/FollowingStatus'
              - default: ACCEPTED
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/users/followers:
    get:
      summary: List followers
      description: >-
        Returns a paginated list of users who follow the authenticated user. Can
        filter by follow status (ACCEPTED, PENDING, REJECTED) or return all
        statuses. By default returns only ACCEPTED followers. Includes both
        local and remote followers.
      tags:
        - Follow
      parameters:
        - name: anyStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: 'The target Follow status like: ACCEPTED/REJECTED/PENDING'
          required: false
          name: status
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/FollowingStatus'
              - default: ACCEPTED
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/users/invite:
    post:
      summary: Send invitation to a user for an entity
      description: >-
        Invites a local or remote user to join a local or remote entity (such as
        a group). For remote users or entities, include the domain in the
        username (e.g., user@domain.com). The invitation must be explicitly
        accepted or rejected by the invitee.
      tags:
        - Invites
      parameters:
        - description: The username and domain of the entity
          required: true
          name: entity
          in: query
          schema:
            type: string
        - description: The username and domain of the invitee
          required: true
          name: invitee
          in: query
          schema:
            type: string
        - description: http vs. https.  For testing ONLY
          required: false
          name: scheme
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/AppScheme'
              - default: https
      responses:
        '200':
          description: User successfully invited to entity. Record created.
          content:
            application/json:
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ClientError:
                  description: Invalid request from client
                  value:
                    errorCode: ClientError
                    message: Invalid request from client
                ConnectingBlockedActorsNotAllowed:
                  description: Connecting blocked actors not allowed
                  value:
                    errorCode: ConnectingBlockedActorsNotAllowed
                    message: Connecting blocked actors not allowed
                InvitesRecordAlreadyExists:
                  description: Invite record already exists
                  value:
                    errorCode: InvitesRecordAlreadyExists
                    message: Invite record already exists
                WrongProtocol:
                  description: Application protocol mismatch
                  value:
                    errorCode: WrongProtocol
                    message: Application protocol mismatch
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: InvitesRecordNotFound
                message: Invite record not found
          description: Invite record not found
      security:
        - header: []
  /api/v1/users/invite-links:
    get:
      summary: List invite links for current user
      tags:
        - SignupInviteLinks
      parameters:
        - description: Filter by active state
          required: false
          name: active
          in: query
          schema:
            type: boolean
            nullable: true
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupInviteLinkList'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
    post:
      summary: Create a new signup invite link
      tags:
        - SignupInviteLinks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignupInviteLinkCreate'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupInviteLink'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                InvitesNotEnabled:
                  description: Invite links are not enabled
                  value:
                    errorCode: InvitesNotEnabled
                    message: Invite links are not enabled
                TooManyInviteLinks:
                  description: Maximum number of active invite links reached
                  value:
                    errorCode: TooManyInviteLinks
                    message: Maximum number of active invite links reached
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/users/invite-links/deactivate/{code}:
    put:
      summary: Deactivate an invite link
      tags:
        - SignupInviteLinks
      parameters:
        - description: Invite code
          required: true
          name: code
          in: path
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/users/invite/accept:
    post:
      summary: Accept an invitation
      description: >-
        Accepts a received invitation to join an entity. This confirms the
        invitee's willingness to join the entity (such as a group). The
        invitation must be in pending status to be accepted.
      tags:
        - Invites
      parameters:
        - description: The username and domain of the entity
          required: true
          name: entity
          in: query
          schema:
            type: string
        - description: The username and domain of the inviter
          required: true
          name: inviter
          in: query
          schema:
            type: string
        - description: http vs. https.  For testing ONLY
          required: false
          name: scheme
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/AppScheme'
              - default: https
      responses:
        '200':
          description: Invite successfully accepted.
          content:
            application/json:
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ClientError:
                  description: Invalid request from client
                  value:
                    errorCode: ClientError
                    message: Invalid request from client
                ConnectingBlockedActorsNotAllowed:
                  description: Connecting blocked actors not allowed
                  value:
                    errorCode: ConnectingBlockedActorsNotAllowed
                    message: Connecting blocked actors not allowed
                InvitesRecordAlreadyExists:
                  description: Invite record already exists
                  value:
                    errorCode: InvitesRecordAlreadyExists
                    message: Invite record already exists
                WrongProtocol:
                  description: Application protocol mismatch
                  value:
                    errorCode: WrongProtocol
                    message: Application protocol mismatch
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: InvitesRecordNotFound
                message: Invite record not found
          description: Invite record not found
      security:
        - header: []
  /api/v1/users/invite/invitee/entities:
    get:
      summary: List entities user was invited to
      description: >-
        Returns all entities (such as groups) that the authenticated user has
        been invited to join. Can be filtered by invitation status.
      tags:
        - Invites
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: Target Invite status (ACCEPTED/REJECTED/PENDING)
          required: false
          name: status
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/InviteStatus'
              - default: PENDING
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of entity User objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/users/invite/invitee/entities/{inviterUser}:
    get:
      summary: List entities from specific inviter
      description: >-
        Returns entities that a specific inviter has invited the authenticated
        user to join. Can be filtered by invitation status.
      tags:
        - Invites
      parameters:
        - description: Inviter
          required: true
          name: inviterUser
          in: path
          schema:
            type: string
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Protocol scheme.
          required: false
          name: scheme
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/AppScheme'
              - default: https
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: Target Invite status (ACCEPTED/REJECTED/PENDING)
          required: false
          name: status
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/InviteStatus'
              - default: PENDING
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of entity User objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/users/invite/invitee/inviters:
    get:
      summary: List users who sent invitations
      description: >-
        Returns a list of users who have sent invitations to the authenticated
        user. Can be filtered by invitation status (pending, accepted, or
        rejected).
      tags:
        - Invites
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: Target Invite status (ACCEPTED/REJECTED/PENDING)
          required: false
          name: status
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/InviteStatus'
              - default: PENDING
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of the inviter User objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/users/invite/invitee/inviters/{entityUser}:
    get:
      summary: List inviters for a specific entity
      description: >-
        Returns users who have invited the authenticated user to a specific
        entity (such as a group). Can be filtered by invitation status.
      tags:
        - Invites
      parameters:
        - description: Entity user name
          required: true
          name: entityUser
          in: path
          schema:
            type: string
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Protocol scheme.
          required: false
          name: scheme
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/AppScheme'
              - default: https
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: Target Invite status (ACCEPTED/REJECTED/PENDING)
          required: false
          name: status
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/InviteStatus'
              - default: PENDING
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of inviter User objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/users/invite/inviter/entities:
    get:
      summary: List entities inviter has invited to
      description: >-
        Returns all entities that the authenticated user (as inviter) has
        invited other users to join. Can be filtered by invitation status.
      tags:
        - Invites
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: Target Invite status (ACCEPTED/REJECTED/PENDING)
          required: false
          name: status
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/InviteStatus'
              - default: PENDING
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of entity User objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/users/invite/inviter/invitees:
    get:
      summary: List users invited by the authenticated user
      description: >-
        Returns all users that the authenticated user has invited to any entity.
        Can be filtered by invitation status.
      tags:
        - Invites
      parameters:
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: Target Invite status (ACCEPTED/REJECTED/PENDING)
          required: false
          name: status
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/InviteStatus'
              - default: PENDING
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of invitee User objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/users/invite/inviter/invitees/{entityUser}:
    get:
      summary: List invitees for specific entity
      description: >-
        Returns users that the authenticated user has invited to a specific
        entity (such as a group). Can be filtered by invitation status.
      tags:
        - Invites
      parameters:
        - description: Entity user
          required: true
          name: entityUser
          in: path
          schema:
            type: string
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: Protocol scheme.
          required: false
          name: scheme
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/AppScheme'
              - default: https
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: Target Invite status (ACCEPTED/REJECTED/PENDING)
          required: false
          name: status
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/InviteStatus'
              - default: PENDING
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of invitee User objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: ResourceNotFound
                message: The requested resource not found
          description: The requested resource not found
      security:
        - header: []
  /api/v1/users/invite/reject:
    post:
      summary: Reject an invitation
      description: >-
        Rejects a received invitation to join an entity. This declines the
        invitation and updates its status to rejected. The invitation must be in
        pending status to be rejected.
      tags:
        - Invites
      parameters:
        - description: The username and domain of the entity
          required: true
          name: entity
          in: query
          schema:
            type: string
        - description: The username and domain of the inviter
          required: true
          name: inviter
          in: query
          schema:
            type: string
        - description: http vs. https.  For testing ONLY
          required: false
          name: scheme
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/AppScheme'
              - default: https
      responses:
        '200':
          description: Invite successfully rejected.
          content:
            application/json:
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ClientError:
                  description: Invalid request from client
                  value:
                    errorCode: ClientError
                    message: Invalid request from client
                ConnectingBlockedActorsNotAllowed:
                  description: Connecting blocked actors not allowed
                  value:
                    errorCode: ConnectingBlockedActorsNotAllowed
                    message: Connecting blocked actors not allowed
                InvitesRecordAlreadyExists:
                  description: Invite record already exists
                  value:
                    errorCode: InvitesRecordAlreadyExists
                    message: Invite record already exists
                WrongProtocol:
                  description: Application protocol mismatch
                  value:
                    errorCode: WrongProtocol
                    message: Application protocol mismatch
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: InvitesRecordNotFound
                message: Invite record not found
          description: Invite record not found
      security:
        - header: []
  /api/v1/users/invite/undo:
    post:
      summary: Revoke an invitation
      description: >-
        Revokes a previously sent invitation to a user for an entity. This
        removes the pending invitation and prevents the user from accepting it.
        For remote users, include the domain in the username.
      tags:
        - Invites
      parameters:
        - description: The username and domain of the entity
          required: true
          name: entity
          in: query
          schema:
            type: string
        - description: The username and domain of the invitee
          required: true
          name: invitee
          in: query
          schema:
            type: string
        - description: http vs. https.  For testing ONLY
          required: false
          name: scheme
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/AppScheme'
              - default: https
      responses:
        '200':
          description: User successfully uninvited from entity. Record deleted.
          content:
            application/json:
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                ClientError:
                  description: Invalid request from client
                  value:
                    errorCode: ClientError
                    message: Invalid request from client
                ConnectingBlockedActorsNotAllowed:
                  description: Connecting blocked actors not allowed
                  value:
                    errorCode: ConnectingBlockedActorsNotAllowed
                    message: Connecting blocked actors not allowed
                InvitesRecordAlreadyExists:
                  description: Invite record already exists
                  value:
                    errorCode: InvitesRecordAlreadyExists
                    message: Invite record already exists
                WrongProtocol:
                  description: Application protocol mismatch
                  value:
                    errorCode: WrongProtocol
                    message: Application protocol mismatch
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: InvitesRecordNotFound
                message: Invite record not found
          description: Invite record not found
      security:
        - header: []
  /api/v1/users/relationships:
    get:
      summary: Get relationships with users
      description: >-
        Returns relationship status between the authenticated user and specified
        target users. Shows following/followed status and optionally
        blocked/muted/notes. Returns a map of user IDs to relationship objects.
        If no relationship exists for a user ID, it's omitted from the response.
        Useful for bulk checking relationship status.
      tags:
        - Follow
      parameters:
        - description: >-
            Include additional relationships, like
            following/followed/blocked/blocked_by/muted/note.
                                         If no 'filter' is provided, following and followed are enabled
          required: false
          name: filter
          in: query
          schema:
            uniqueItems: true
            type: array
            items:
              type: string
            nullable: true
        - description: Target users to get relationship with
          required: true
          name: targets
          in: query
          schema:
            minItems: 1
            uniqueItems: true
            type: array
            items:
              $ref: '#/components/schemas/TypeId'
      responses:
        '200':
          description: >-
            If userId is missing from response, no relationships found, no one
            follows anyone
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Relationship'
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
      security:
        - header: []
  /api/v1/users/remote/{userNameFull}/followers:
    get:
      summary: Get remote user's followers
      description: >-
        Retrieves the follower collection of a remote federated user. Fetches
        the followers from the remote server using ActivityPub protocol.
        Supports pagination through offset and limit parameters. Only works for
        remote users, not local users.
      tags:
        - Remote collections
      parameters:
        - description: Username with the domain
          example: user@dust.allroads.social
          required: true
          name: userNameFull
          in: path
          schema:
            type: string
        - description: Show no more than the given number of users
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: An offset to show users starting from
          required: false
          name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: RemoteCollectionsNotRemote
                message: User is not a remote user
          description: User is not a remote user
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: RemoteCollectionsCannotFindUser
                message: Cannot find remote user
          description: Cannot find remote user
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: RemoteCollectionsFailedFetch
                message: Failed to fetch remote collections
          description: Failed to fetch remote collections
      security: []
  /api/v1/users/remote/{userNameFull}/following:
    get:
      summary: Get remote user's following
      description: >-
        Retrieves the following collection of a remote federated user. Fetches
        the list of accounts that the remote user follows from their home server
        using ActivityPub protocol. Supports pagination through offset and limit
        parameters. Only works for remote users, not local users.
      tags:
        - Remote collections
      parameters:
        - description: Username with the domain
          example: user@dust.allroads.social
          required: true
          name: userNameFull
          in: path
          schema:
            type: string
        - description: Show no more than the given number of users
          required: false
          name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - description: An offset to show users starting from
          required: false
          name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: RemoteCollectionsNotRemote
                message: User is not a remote user
          description: User is not a remote user
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: RemoteCollectionsCannotFindUser
                message: Cannot find remote user
          description: Cannot find remote user
        '500':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: RemoteCollectionsFailedFetch
                message: Failed to fetch remote collections
          description: Failed to fetch remote collections
      security: []
  /api/v1/users/rename-history:
    get:
      summary: Get list of username changes
      tags:
        - Users
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsernameHistories'
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security:
        - header: []
  /api/v1/users/{userId}:
    put:
      summary: Update user's profile
      description: >-
        User's profile includes: displayName, username, summary, avatarId,
        headerId
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFull'
        '400':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              examples:
                TimezoneCannotUpdate:
                  description: Failed to update the timezone
                  value:
                    errorCode: TimezoneCannotUpdate
                    message: Failed to update the timezone
                UserLocationAutoUpdateNeedGeo:
                  description: geo coding is required when autoUpdate is true
                  value:
                    errorCode: UserLocationAutoUpdateNeedGeo
                    message: geo coding is required when autoUpdate is true
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security:
        - header: []
    get:
      summary: Get user by userId
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            If true return also summary, stats, header and fields. Default
            false.
          required: false
          name: full
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include blocked_by status (target blocked viewer)
          required: false
          name: includeBlockedByStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include blocked status (viewer blocked target)
          required: false
          name: includeBlockedStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include followed status
          required: false
          name: includeFollowedStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include following status
          required: false
          name: includeFollowingStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: Include muted status
          required: false
          name: includeMutedStatus
          in: query
          schema:
            type: boolean
            nullable: true
        - description: >-
            Include all relationship statuses (following, followed, blocked,
            blocked_by, muted)
          required: false
          name: relations
          in: query
          schema:
            type: boolean
            nullable: true
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/User'
                  - $ref: '#/components/schemas/UserFull'
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security: []
  /api/v1/users/{userId}/followers:
    get:
      summary: Users which follow the given account
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of followers as User objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: FollowersListHidden
                message: The user has hidden their followers list
          description: The user has hidden their followers list
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security: []
  /api/v1/users/{userId}/following:
    get:
      summary: Users which the given account follows
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - description: >-
            Get older records (records with IDs less than this value) Alias
            maxId/max_id
          example: '?lastId=${data.last().id}'
          required: false
          name: lastId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
        - name: limit
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: offset
          in: query
          schema:
            format: int32
            type: integer
            nullable: true
        - name: sortBy
          in: query
          schema:
            type: string
            nullable: true
        - name: sortOrder
          in: query
          schema:
            type: string
            nullable: true
        - description: >-
            Get newer records (records with IDs greater than this value) Alias
            minId/min_id
          example: '?untilId=${data.first().id}'
          required: false
          name: untilId
          in: query
          schema:
            allOf:
              - $ref: '#/components/schemas/TypeId'
            nullable: true
      responses:
        '200':
          description: List of following as User objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '403':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: FollowingListHidden
                message: The user has hidden their following list
          description: The user has hidden their following list
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security: []
  /api/v1/users/{userId}/media:
    put:
      summary: Update user avatar and header
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TypeId'
        - name: htmlContent
          in: query
          description: >-
            Returns text as html if true or original text if false. Applicable
            only to local posts and users. Default is true.
          required: false
          schema: {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateMedia'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFull'
        '400':
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: AuthUnauthorized
                message: A valid authentication token is required
          description: A valid authentication token is required
        '404':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ApiError'
              example:
                errorCode: UserNotFound
                message: User not found
          description: User not found
      security:
        - header: []
  /test-authenticated/authenticated-with-rbac:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Authenticated With Rbac
      tags:
        - Test Authenticated Controller
      security:
        - header: []
  /test-authenticated/method-authenticated:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Method Authenticated
      tags:
        - Test Authenticated Controller
      security:
        - header: []
  /test-class-auth/inherit:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Inherit Class Auth
      tags:
        - Test Class Auth Controller
      security: []
  /test-class-auth/override:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Override Class Auth
      tags:
        - Test Class Auth Controller
      security: []
  /test-class-auth/public-override:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Public Override Auth
      tags:
        - Test Class Auth Controller
      security: []
  /test-class-authenticated/authenticated-with-permit-all:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Authenticated With Permit All
      tags:
        - Test Class Authenticated Controller
      security:
        - header: []
  /test-class-authenticated/inherit-authenticated:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Inherit Authenticated
      tags:
        - Test Class Authenticated Controller
      security:
        - header: []
  /test-class-permit-all/inherit-permit-all:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Inherit Permit All
      tags:
        - Test Class Permit All Controller
      security: []
  /test-class-permit-all/method-overrides-class-permit-all:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Method Overrides Class Permit All
      tags:
        - Test Class Permit All Controller
      security: []
  /test-permit-all/method-permit-all:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Method Permit All
      tags:
        - Test Permit All Controller
      security: []
  /test-permit-all/permit-all-overrides-allow:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Permit All Overrides Allow
      tags:
        - Test Permit All Controller
      security: []
  /test-permit-all/permit-all-overrides-allow-any:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Permit All Overrides Allow Any
      tags:
        - Test Permit All Controller
      security: []
  /test/admin-only:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Admin Only Endpoint
      tags:
        - Test Authorization Controller
      security: []
  /test/business/admin-delete-everything:
    post:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Admin Delete Everything
      tags:
        - Test Authorization Controller
      security: []
  /test/business/basic-read-access:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Basic Read Access
      tags:
        - Test Authorization Controller
      security: []
  /test/business/delete-user-and-group:
    post:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Delete User And Group
      tags:
        - Test Authorization Controller
      security: []
  /test/business/full-admin-action:
    post:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Full Admin Action
      tags:
        - Test Authorization Controller
      security: []
  /test/business/high-privilege-any:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: High Privilege Any
      tags:
        - Test Authorization Controller
      security: []
  /test/business/reports-only:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: View Reports Only
      tags:
        - Test Authorization Controller
      security: []
  /test/business/view-user-or-groups:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: View User Or Group Members
      tags:
        - Test Authorization Controller
      security: []
  /test/cache-stats:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Get Cache Stats
      tags:
        - Test Authorization Controller
      security: []
  /test/clear-cache:
    post:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Clear Cache
      tags:
        - Test Authorization Controller
      security: []
  /test/config:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Get Config
      tags:
        - Test Authorization Controller
      security: []
  /test/public:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Public Endpoint
      tags:
        - Test Authorization Controller
      security: []
  /test/roles:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Get Roles
      tags:
        - Test Authorization Controller
      security: []
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: string
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
      summary: Create Role
      tags:
        - Test Authorization Controller
      security: []
  /test_transaction/ok:
    post:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: {}
      summary: Ok
      tags:
        - Quarkus Test Resource For Transaction
      security: []
info:
  title: Wellesley Platform API
  version: '1.0'
servers:
  - url: https://dust.allroads.social
    description: Simple setup, all in one. Digital Ocean
  - url: https://meteor.allroads.social
    description: Simple setup, db is separate. Digital Ocean
security:
  - header: []
