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.

  /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
        '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. No error is raised if the recipient does not exist or the user is offline. The sender screen name does not need to exist.
      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.
      responses:
        '200':
          description: Message sent successfully.
        '400':
          description: Bad request. Invalid input data.

  /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

  /admin/webapi/keys:
    get:
      summary: List all Web API keys
      description: Retrieve a list of all Web API keys for the Web AIM API.
      tags: [ Web API Management ]
      responses:
        '200':
          description: Successful response containing a list of API keys.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebAPIKey'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'

    post:
      summary: Create a new Web API key
      description: Create a new API key for Web AIM API authentication.
      tags: [ Web API Management ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - app_name
              properties:
                app_name:
                  type: string
                  description: Name of the application using this API key.
                  example: "My Web AIM Client"
                allowed_origins:
                  type: array
                  items:
                    type: string
                  description: List of allowed CORS origins. Empty list allows all origins (useful for mobile apps).
                  example: [ "https://example.com", "https://app.example.com" ]
                rate_limit:
                  type: integer
                  description: Maximum requests per minute allowed for this key.
                  default: 60
                  example: 120
                capabilities:
                  type: array
                  items:
                    type: string
                  description: List of capabilities/features enabled for this key. Empty list allows all capabilities.
                  example: [ "aim.session", "presence.get", "im.send" ]
      responses:
        '201':
          description: API key created successfully.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/WebAPIKey'
                  - type: object
                    properties:
                      dev_key:
                        type: string
                        description: The actual API key value. This is only shown once at creation time.
                        example: "a1b2c3d4e5f6789012345678901234567890123456789012345678901234"
        '400':
          description: Bad request. Invalid input data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '409':
          description: Conflict. An API key with this ID already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'

  /admin/webapi/keys/{id}:
    get:
      summary: Get a specific Web API key
      description: Retrieve details of a specific Web API key by its developer ID.
      tags: [ Web API Management ]
      parameters:
        - name: id
          in: path
          description: The developer ID of the API key.
          required: true
          schema:
            type: string
            example: "dev_550e8400-e29b-41d4-a716-446655440000"
      responses:
        '200':
          description: Successful response containing the API key details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebAPIKey'
        '404':
          description: API key not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'

    put:
      summary: Update a Web API key
      description: Update settings for an existing Web API key.
      tags: [ Web API Management ]
      parameters:
        - name: id
          in: path
          description: The developer ID of the API key.
          required: true
          schema:
            type: string
            example: "dev_550e8400-e29b-41d4-a716-446655440000"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                app_name:
                  type: string
                  description: New application name.
                is_active:
                  type: boolean
                  description: Enable or disable the API key.
                rate_limit:
                  type: integer
                  description: New rate limit (requests per minute).
                allowed_origins:
                  type: array
                  items:
                    type: string
                  description: New list of allowed CORS origins.
                capabilities:
                  type: array
                  items:
                    type: string
                  description: New list of enabled capabilities.
      responses:
        '200':
          description: API key updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebAPIKey'
        '404':
          description: API key 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 Web API key
      description: Permanently delete a Web API key.
      tags: [ Web API Management ]
      parameters:
        - name: id
          in: path
          description: The developer ID of the API key.
          required: true
          schema:
            type: string
            example: "dev_550e8400-e29b-41d4-a716-446655440000"
      responses:
        '204':
          description: API key deleted successfully.
        '404':
          description: API key not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'

  /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.
          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)

    WebAPIKey:
      type: object
      properties:
        dev_id:
          type: string
          description: Unique developer/application identifier.
          example: "dev_550e8400-e29b-41d4-a716-446655440000"
        app_name:
          type: string
          description: Name of the application using this API key.
          example: "My Web AIM Client"
        created_at:
          type: string
          format: date-time
          description: Timestamp when the key was created.
        last_used:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the key was last used.
        is_active:
          type: boolean
          description: Whether the API key is currently active.
          default: true
        rate_limit:
          type: integer
          description: Maximum requests per minute allowed.
          example: 60
        allowed_origins:
          type: array
          items:
            type: string
          description: List of allowed CORS origins. Empty list allows all origins.
          example: [ "https://example.com" ]
        capabilities:
          type: array
          items:
            type: string
          description: List of enabled features/endpoints. Empty list allows all capabilities.
          example: [ "aim.session", "presence.get" ]