mk6i-open-oscar-server/api.yml

openapi: 3.0.3
info:
  title: User Management API
  description: API that provides management functionality for Open OSCAR Server operators.
  version: 1.0.0
paths:
  /user:
    get:
      summary: Get all users
      description: Retrieve a list of all user accounts.
      responses:
        '200':
          description: Successful response containing a list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: User's unique identifier.
                    screen_name:
                      type: string
                      description: User's AIM screen name or ICQ UIN.
                    is_icq:
                      type: boolean
                      description: If true, indicates an ICQ user instead of an AIM user.
                    suspended_status:
                      type: string
                      description: User's suspended status
                    is_bot:
                      type: boolean
                      nullable: true
                      description: Indicates whether the user is a bot.
    post:
      summary: Create a new user
      description: Create a new AIM or ICQ user account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - screen_name
                - password
              properties:
                screen_name:
                  type: string
                  description: The user's AIM screen name or ICQ UIN.
                password:
                  type: string
                  description: The user's password for account creation.
      responses:
        '201':
          description: User account created successfully.
        '400':
          description: Bad request. Invalid input data.
        '409':
          description: Conflict. A user with the specified screen name or ICQ UIN already exists.
    delete:
      summary: Delete a user
      description: Delete a user account specified by their screen name.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                screen_name:
                  type: string
                  description: The screen name of the user to delete.
      responses:
        '204':
          description: User deleted successfully.
        '404':
          description: User not found.

  /user/{screenname}/account:
    get:
      summary: Get account details for a specific screen name.
      description: Retrieve account details for a specific screen name.
      parameters:
        - in: path
          name: screenname
          schema:
            type: string
          description: User's AIM screen name or ICQ UIN.
          required: true
      responses:
        '200':
          description: Successful response containing account details
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: User's unique identifier.
                  screen_name:
                    type: string
                    description: User's AIM screen name or ICQ UIN.
                  profile:
                    type: string
                    description: User's AIM profile HTML.
                  email_address:
                    type: string
                    description: User's email address
                  confirmed:
                    type: boolean
                    description: User's account confirmation status
                  is_icq:
                    type: boolean
                    description: If true, indicates an ICQ user instead of an AIM user.
                  suspended_status:
                    type: string
                    description: User's suspended status
                  is_bot:
                    type: boolean
                    nullable: true
                    description: Indicates whether the user is a bot.
        '404':
          description: User not found.
    patch:
      summary: Update a user account
      description: Update attributes for a user account
      parameters:
        - in: path
          name: screenname
          schema:
            type: string
          description: User's AIM screen name or ICQ UIN.
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                suspended_status:
                  type: string
                  nullable: true
                  enum: [ deleted, expired, suspended, suspended_age ]
                  description: The suspended status of the account
                is_bot:
                  type: boolean
                  nullable: true
                  description: >
                    Indicates whether the account is for a bot. Bots are exempt from rate limiting... make sure you
                    trust the bot and bot owner before enabling this flag.
      responses:
        '204':
          description: Successfully updated user account
        '304':
          description: Did not modify user account
        '400':
          description: Bad request when modifying user account
        '404':
          description: User not found

  /user/{screenname}/icon:
    get:
      summary: Get AIM buddy icon for a screen name
      description: Retrieve account buddy icon for a specific screen name.
      parameters:
        - in: path
          name: screenname
          schema:
            type: string
          description: User's AIM screen name or ICQ UIN.
          required: true
      responses:
        '200':
          description: Successful response containing buddy icon bytes
          content:
            image/gif:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: User not found, or user has no buddy icon

  /session:
    get:
      summary: Get active sessions
      description: Retrieve a list of active sessions of logged in users.
      responses:
        '200':
          description: Successful response containing a list of active sessions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: The number of active sessions.
                  sessions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: User's unique identifier.
                        screen_name:
                          type: string
                          description: User's AIM screen name or ICQ UIN.
                        online_seconds:
                          type: integer
                          description: Number of seconds this user session has been online.
                        is_away:
                          type: boolean
                          description: If true, indicates the user is away.
                        away_message:
                          type: string
                          description: User's AIM away message HTML.
                        idle_seconds:
                          type: integer
                          description: Number of seconds this user session has been idle. 0 if not idle.
                        is_invisible:
                          type: boolean
                          description: If true, indicates the user is invisible.
                        is_icq:
                          type: boolean
                          description: If true, indicates an ICQ user instead of an AIM user.
                        instance_count:
                          type: integer
                          description: Number of concurrent clients signed in for this user.
                        instances:
                          type: array
                          description: Array of session instances for this user.
                          items:
                            type: object
                            properties:
                              num:
                                type: integer
                                description: Instance number for this session instance.
                              idle_seconds:
                                type: integer
                                description: Number of seconds this instance has been idle. 0 if not idle.
                              is_away:
                                type: boolean
                                description: If true, indicates this instance is away.
                              away_message:
                                type: string
                                description: This instance's AIM away message HTML.
                              is_invisible:
                                type: boolean
                                description: If true, indicates this instance is invisible.
                              remote_addr:
                                type: string
                                description: Remote IP address of the user's connection to BOS or TOC.
                              remote_port:
                                type: integer
                                description: Remote port number of the user's connection to BOS or TOC.
                              client_id:
                                type: string
                                description: Client name and version reported by the client at sign-on. Empty if not reported.

  /session/{screenname}:
    get:
      summary: Get active sessions for a given screen name or UIN.
      description: Retrieve a list of active sessions of a specific logged in user.
      parameters:
        - in: path
          name: screenname
          schema:
            type: string
          description: User's AIM screen name or ICQ UIN.
          required: true
      responses:
        '200':
          description: Successful response containing a list of active sessions for the given screen name
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: The number of active sessions.
                  sessions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: User's unique identifier.
                        screen_name:
                          type: string
                          description: User's AIM screen name or ICQ UIN.
                        online_seconds:
                          type: number
                          description: Number of seconds this user session has been online.
                        away_message:
                          type: string
                          description: User's AIM away message HTML. Empty if the user is not away.
                        idle_seconds:
                          type: number
                          description: Number of seconds this user session has been idle. 0 if not idle.
                        is_invisible:
                          type: boolean
                          description: If true, indicates the user is invisible.
                        is_icq:
                          type: boolean
                          description: If true, indicates an ICQ user instead of an AIM user.
                        instances:
                          type: array
                          description: Array of session instances for this user.
                          items:
                            type: object
                            properties:
                              num:
                                type: integer
                                description: Instance number for this session instance.
                              idle_seconds:
                                type: integer
                                description: Number of seconds this instance has been idle. 0 if not idle.
                              is_away:
                                type: boolean
                                description: If true, indicates this instance is away.
                              away_message:
                                type: string
                                description: This instance's AIM away message HTML.
                              is_invisible:
                                type: boolean
                                description: If true, indicates this instance is invisible.
                              remote_addr:
                                type: string
                                description: Remote IP address of the user's connection to BOS or TOC
                              remote_port:
                                type: integer
                                description: Remote port number of the user's connection to BOS or TOC
                              client_id:
                                type: string
                                description: Client name and version reported by the client at sign-on. Empty if not reported.
        '404':
          description: User not found.
    delete:
      summary: Delete active sessions for a given screen name or UIN.
      description: Disconnect any active sessions of a specific logged in user.
      parameters:
        - in: path
          name: screenname
          schema:
            type: string
          description: User's AIM screen name or ICQ UIN.
          required: true
      responses:
        '204':
          description: Session deleted successfully
        '404':
          description: Session not found

  /user/password:
    put:
      summary: Set a user's password
      description: Update the password for a user specified by their screen name or ICQ UIN.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - screen_name
                - password
              properties:
                screen_name:
                  type: string
                  description: The AIM screen name or ICQ UIN of the user whose password is to be updated.
                password:
                  type: string
                  description: The new password for the user.
      responses:
        '204':
          description: Password updated successfully.
        '400':
          description: Bad request. Invalid input data.
        '404':
          description: User not found.

  /chat/room/public:
    get:
      summary: List all public AIM chat rooms
      description: Retrieve a list of all public AIM chat rooms in exchange 5.
      responses:
        '200':
          description: Successful response containing a list of chat rooms.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Name of the chat room.
                    create_time:
                      type: string
                      format: date-time
                      description: The timestamp when the chat room was created.
                    participants:
                      type: array
                      description: List of participants in the chat room.
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                            description: User's unique identifier.
                          screen_name:
                            type: string
                            description: User's AIM screen name.

    post:
      summary: Create a new public chat room
      description: Create a new public chat room in exchange 5.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the chat room.
      responses:
        '201':
          description: Chat room created successfully.
        '400':
          description: Bad request. Invalid input data.
        '409':
          description: Chat room already exists.

    delete:
      summary: Delete public chat rooms
      description: Delete one or more public chat rooms in exchange 5.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - names
              properties:
                names:
                  type: array
                  description: List of chat room names to delete.
                  items:
                    type: string
      responses:
        '204':
          description: Chat rooms deleted successfully.
        '400':
          description: Bad request. Invalid input data.
        '500':
          description: Internal server error.

  /chat/room/private:
    get:
      summary: List all private AIM chat rooms
      description: Retrieve a list of all private AIM chat rooms in exchange 4.
      responses:
        '200':
          description: Successful response containing a list of chat rooms.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Name of the chat room.
                    create_time:
                      type: string
                      format: date-time
                      description: The timestamp when the chat room was created.
                    creator_id:
                      type: string
                      description: The chat room creator user ID.
                    participants:
                      type: array
                      description: List of participants in the chat room.
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                            description: User's unique identifier.
                          screen_name:
                            type: string
                            description: User's AIM screen name.

  /instant-message:
    post:
      summary: Send an instant message
      description: |
        Send an instant message from one user to another. Both the sender and the
        recipient must be valid accounts. When sending from a system account, make
        sure that account exists.

        If the recipient is offline, the message is stored for delivery at their next
        login when storeOffline is true; otherwise a 404 is returned.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: string
                  description: The AIM screen name or ICQ UIN of the sender.
                to:
                  type: string
                  description: The AIM screen name or ICQ UIN of the recipient.
                text:
                  type: string
                  description: The text content of the message.
                storeOffline:
                  type: boolean
                  default: false
                  description: If true, store the message for an offline recipient instead of returning 404.
      responses:
        '200':
          description: Message sent or stored for offline delivery.
        '400':
          description: Bad request. Invalid input data, or the sender does not exist.
        '403':
          description: Message blocked by the recipient.
        '404':
          description: Recipient is offline and the message was not stored, either because storeOffline is false or because the recipient does not exist, does not accept offline messages, or has a full offline inbox.

  /version:
    get:
      summary: Get build information of RAS.
      description: Retrieve the build version, git commit, and build date of the running RAS binary.
      responses:
        '200':
          description: Successful response containing the build information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    description: The release version number.
                  commit:
                    type: string
                    description: The latest git commit hash in this build.
                  date:
                    type: string
                    description: The build date and timestamp in RFC3339 format.

  /directory/category:
    get:
      summary: Get all keyword categories
      description: Retrieve a list of all keyword categories.
      responses:
        '200':
          description: Successful response containing a list of keyword categories.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      description: The unique identifier of the keyword category.
                    name:
                      type: string
                      description: The name of the keyword category.
    post:
      summary: Create a new keyword category
      description: Create a new keyword category.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: The name of the keyword category.
      responses:
        '201':
          description: Keyword category created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: The keyword category ID.
                  name:
                    type: string
                    description: The name of the keyword category.
        '400':
          description: Malformed input body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '409':
          description: A category with the specified name already exists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

  /directory/category/{id}:
    delete:
      summary: Delete a keyword category
      description: Delete a keyword category specified by its ID.
      parameters:
        - name: id
          in: path
          description: The ID of the keyword category.
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Keyword category deleted successfully.
        '400':
          description: Invalid category ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '404':
          description: Keyword category not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '409':
          description: The keyword category is currently in use and cannot be deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

  /directory/category/{id}/keyword:
    get:
      summary: Get all keywords in a category
      description: Retrieve a list of all keywords in the specified category.
      parameters:
        - name: id
          in: path
          description: The ID of the keyword category.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response containing a list of keywords.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      description: The unique identifier of the keyword.
                    name:
                      type: string
                      description: The name of the keyword.
        '400':
          description: Invalid category ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '404':
          description: Keyword category not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

  /directory/keyword:
    post:
      summary: Create a new keyword.
      description: Create a new keyword in a category.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - category_id
                - name
              properties:
                category_id:
                  type: integer
                  description: The ID of the parent keyword category.
                name:
                  type: string
                  description: The name of the keyword.
      responses:
        '201':
          description: Keyword created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: The keyword ID.
                  name:
                    type: string
                    description: The name of the keyword.
        '400':
          description: Malformed input body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '404':
          description: Parent keyword category not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '409':
          description: A keyword with the specified name already exists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

  /directory/keyword/{id}:
    delete:
      summary: Delete a keyword
      description: Delete a keyword specified by its ID.
      parameters:
        - name: id
          in: path
          description: The ID of the keyword.
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Keyword deleted successfully.
        '404':
          description: Keyword not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '409':
          description: Conflict. The keyword is currently in use and cannot be deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

  /directory/aim:
    get:
      summary: Get all AIM user directory entries
      description: Retrieve the AIM user directory entries of all users who have directory info or keywords set.
      responses:
        '200':
          description: Successful response containing a list of directory entries.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    screen_name:
                      type: string
                      description: The user's display screen name.
                    first_name:
                      type: string
                      description: The user's first name.
                    middle_name:
                      type: string
                      description: The user's middle name.
                    last_name:
                      type: string
                      description: The user's last name.
                    maiden_name:
                      type: string
                      description: The user's maiden name.
                    nickname:
                      type: string
                      description: The user's nickname.
                    city:
                      type: string
                      description: The user's city.
                    state:
                      type: string
                      description: The user's state or region.
                    country:
                      type: string
                      description: The user's country.
                    address:
                      type: string
                      description: The user's street address.
                    zip:
                      type: string
                      description: The user's ZIP or postal code.
                    keywords:
                      type: array
                      description: The user's directory keywords.
                      items:
                        type: string

  /bart:
    get:
      summary: Get BART entries by type
      description: Retrieve a list of BART (Buddy ART) entries for a specific type.
      parameters:
        - name: type
          in: query
          description: The BART type ID (integer).
          required: true
          schema:
            $ref: '#/components/schemas/BARTType'
      responses:
        '200':
          description: Successful response containing BART entries for the specified type.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    hash:
                      type: string
                      description: A hex value representing the BART asset hash.
                    type:
                      $ref: '#/components/schemas/BARTType'
                      description: The BART type ID.
                  required:
                    - hash
                    - type
        '400':
          description: Bad request. Missing or invalid type parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'

  /bart/{hash}:
    get:
      summary: Get BART asset data
      description: Retrieve the raw binary data for a specific BART asset.
      parameters:
        - name: hash
          in: path
          description: The hex hash value for the BART asset.
          required: true
          schema:
            type: string
            pattern: '^[0-9a-fA-F]+$'
      responses:
        '200':
          description: Successful response containing the raw BART asset data.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request. Missing or invalid hash parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '404':
          description: BART asset not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
    post:
      summary: Upload a BART asset
      description: Upload a Buddy ART asset with the specified hash and type.
      parameters:
        - name: hash
          in: path
          description: The hex hash value for the BART asset.
          required: true
          schema:
            type: string
            pattern: '^[0-9a-fA-F]+$'
        - name: type
          in: query
          description: The BART type ID (integer).
          required: true
          schema:
            $ref: '#/components/schemas/BARTType'
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
              description: Raw bytes of the BART asset
      responses:
        '201':
          description: BART asset uploaded successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  hash:
                    type: string
                    description: A hex value representing the BART asset hash.
                  type:
                    $ref: '#/components/schemas/BARTType'
                    description: The BART type ID.
                required:
                  - hash
                  - type
        '400':
          description: Bad request. Invalid type format, hash format, or failed to read request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '409':
          description: Conflict. BART asset already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '413':
          description: Payload too large. Asset exceeds size limits for the specified type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
    delete:
      summary: Delete a BART asset
      description: Delete a BART asset with the specified hash.
      parameters:
        - name: hash
          in: path
          description: The hex hash value for the BART asset.
          required: true
          schema:
            type: string
            pattern: '^[0-9a-fA-F]+$'
      responses:
        '200':
          description: BART asset deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          description: Bad request. Missing or invalid hash parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '404':
          description: BART asset not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'

  /feedbag/{screen_name}/group:
    get:
      summary: Get buddy list for a user
      description: Retrieve all buddies for a user, grouped by group ID.
      parameters:
        - name: screen_name
          in: path
          description: User's AIM screen name or ICQ UIN.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response containing buddy list grouped by group ID.
          content:
            application/json:
              schema:
                type: array
                description: List of buddy groups.
                items:
                  type: object
                  properties:
                    group_id:
                      type: integer
                      description: The group ID.
                    group_name:
                      type: string
                      description: The name of the group.
                    buddies:
                      type: array
                      description: List of buddies in this group.
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                            description: The buddy's screen name.
                          item_id:
                            type: integer
                            description: The feedbag item ID for this buddy.
                  required:
                    - group_id
                    - group_name
                    - buddies
        '404':
          description: User or feedbag not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'

  /feedbag/{screen_name}/group/{group_name}:
    put:
      summary: Add a group to a user's feedbag
      description: |
        Create a new buddy list group in the user's feedbag. If the feedbag is empty,
        the root group is created automatically. This operation is idempotent — if a
        group with the same name already exists, the request succeeds and returns the
        existing group.
      parameters:
        - name: screen_name
          in: path
          description: User's AIM screen name or ICQ UIN.
          required: true
          schema:
            type: string
        - name: group_name
          in: path
          description: The name of the group to add.
          required: true
          schema:
            type: string
          example: "Friends"
      responses:
        '200':
          description: Group already exists. Operation is idempotent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  group_id:
                    type: integer
                    description: The group ID.
                  group_name:
                    type: string
                    description: The name of the group.
                required:
                  - group_id
                  - group_name
        '201':
          description: Group created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  group_id:
                    type: integer
                    description: The group ID.
                  group_name:
                    type: string
                    description: The name of the group.
                required:
                  - group_id
                  - group_name
        '400':
          description: Bad request. Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '404':
          description: User not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'

  /feedbag/{screen_name}/group/{group_id}/buddy/{buddy_screen_name}:
    put:
      summary: Add a buddy to a group
      description: Add a buddy to a specific group in the user's feedbag. This operation is idempotent - if the buddy already exists in the group, the request will succeed without error.
      parameters:
        - name: screen_name
          in: path
          description: User's AIM screen name or ICQ UIN.
          required: true
          schema:
            type: string
        - name: group_id
          in: path
          description: The group ID to add the buddy to.
          required: true
          schema:
            type: integer
        - name: buddy_screen_name
          in: path
          description: The screen name of the buddy to add.
          required: true
          schema:
            type: string
          example: "buddy123"
      responses:
        '200':
          description: Buddy added or already exists in the group. Operation is idempotent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: The buddy's screen name.
                  group_id:
                    type: integer
                    description: The group ID the buddy was added to.
                  item_id:
                    type: integer
                    description: The feedbag item ID for this buddy.
                required:
                  - name
                  - group_id
                  - item_id
        '400':
          description: Bad request. Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '404':
          description: User or group not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
    delete:
      summary: Delete a buddy from a group
      description: Remove a buddy from a specific group in the user's feedbag.
      parameters:
        - name: screen_name
          in: path
          description: User's AIM screen name or ICQ UIN.
          required: true
          schema:
            type: string
        - name: group_id
          in: path
          description: The group ID to remove the buddy from.
          required: true
          schema:
            type: integer
        - name: buddy_screen_name
          in: path
          description: The screen name of the buddy to remove.
          required: true
          schema:
            type: string
          example: "buddy123"
      responses:
        '204':
          description: Buddy deleted successfully.
        '400':
          description: Bad request. Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '404':
          description: User, group, or buddy not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'


  /user/{screenname}/linked-account:
    get:
      summary: List linked accounts for a screen name
      description: Retrieve all linked accounts associated with a user.
      parameters:
        - in: path
          name: screenname
          schema:
            type: string
          description: User's AIM screen name or ICQ UIN.
          required: true
      responses:
        '200':
          description: Successful response containing linked accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  linked_accounts:
                    type: array
                    items:
                      type: string
                    description: List of linked screen names.
        '404':
          description: User not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
    post:
      summary: Add a linked account
      description: Link a screen name to the specified primary user account.
      parameters:
        - in: path
          name: screenname
          schema:
            type: string
          description: User's AIM screen name or ICQ UIN.
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - linked_screen_name
              properties:
                linked_screen_name:
                  type: string
                  description: The screen name to link to the primary account.
                  example: "secondaryuser"
      responses:
        '201':
          description: Linked account created successfully.
        '400':
          description: Invalid request body, or screen name cannot be linked to itself.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '404':
          description: Primary user or linked user not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '409':
          description: Linked account relationship already exists, or the user already has the maximum of 4 linked accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'

  /user/{screenname}/linked-account/{linked_screenname}:
    delete:
      summary: Remove a linked account
      description: Remove the linked account relationship between a primary screen name and a linked screen name.
      parameters:
        - in: path
          name: screenname
          schema:
            type: string
          description: User's AIM screen name or ICQ UIN.
          required: true
        - in: path
          name: linked_screenname
          schema:
            type: string
          description: The linked screen name to remove.
          required: true
      responses:
        '204':
          description: Linked account removed successfully.
        '404':
          description: User or linked account not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'


components:
  schemas:
    MessageResponse:
      type: object
      properties:
        message:
          type: string
          description: Response message describing the result or error.
      required:
        - message

    BARTType:
      type: integer
      enum: [ 0, 1, 2, 3, 4, 5, 6, 12, 13, 15, 96, 129, 131, 136, 137, 1024, 1026, 1027, 1028 ]
      description: |
        BART (Buddy ART) type identifier. Valid type IDs and their corresponding names:
        - 0: buddy_icon_small (GIF/JPG/BMP, <= 32 pixels and 2k)
        - 1: buddy_icon (GIF/JPG/BMP, <= 64 pixels and 7k)
        - 2: status_str (StringTLV format; DATA flag is always set)
        - 3: arrive_sound (WAV/MP3/MID, <= 10K)
        - 4: rich_text (byte array of rich text codes; DATA flag is always set)
        - 5: superbuddy_icon (XML)
        - 6: radio_station (Opaque struct; DATA flag is always set)
        - 12: buddy_icon_big (SWF)
        - 13: status_str_tod (Time when the status string is set)
        - 15: current_av_track (XML file; Data flag should not be set)
        - 96: depart_sound (WAV/MP3/MID, <= 10K)
        - 129: im_chrome (GIF/JPG/BMP wallpaper)
        - 131: im_sound (WAV/MP3, <= 10K)
        - 136: im_chrome_xml (XML)
        - 137: im_chrome_immers (Immersive Expressions)
        - 1024: emoticon_set (Set of default Emoticons)
        - 1026: encr_cert_chain (Cert chain for encryption certs)
        - 1027: sign_cert_chain (Cert chain for signing certs)
        - 1028: gateway_cert (Cert for enterprise gateway)