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