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_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' 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"]