API docs by Redocly

XMPP Chat Backend REST API (2.0.0)

Download OpenAPI specification:Download

REST API for user management, authentication, groups, presence, and messaging in the Aoba chat backend.

Authentication

Most endpoints require authentication via JWT token. The token is provided:

  • In an HTTP-only cookie (auth_token) after login
  • Or via query parameter (?token=) for mobile apps

Rate Limits

  • Standard endpoints: 100 requests/minute
  • Batch endpoints (metadata, presence): 10 requests/minute
  • Search: 30 requests/minute

Authentication

User registration and authentication operations

Register a new user account

Creates a new user account with username and password

Request Body schema: application/json
required
username
required
string [ 3 .. 255 ] characters ^[a-zA-Z0-9_-]+$

Username (alphanumeric with _ or -)

password
required
string >= 8 characters

Password (at least 8 characters)

Responses

Request samples

Content type
application/json
{
  • "username": "alice",
  • "password": "password123"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "alice",
  • "created_at": "2025-11-27T10:30:00Z"
}

Login to the system

Authenticates user credentials and returns a JWT token

Request Body schema: application/json
required
username
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "username": "alice",
  • "password": "password123"
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "expires_at": "2025-11-28T10:30:00Z",
  • "user": {
    }
}

Logout from the system

Invalidates the current session token

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthorized",
  • "message": "Invalid username or password"
}

Users

User management and search operations

Get current user information

Retrieves information about the authenticated user

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "alice",
  • "created_at": "2025-11-27T10:30:00Z"
}

Delete current user account

Deletes the authenticated user's account

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthorized",
  • "message": "Invalid username or password"
}

Update username

Changes the current user's username

Authorizations:
bearerAuth
Request Body schema: application/json
required
username
required
string [ 3 .. 255 ] characters ^[a-zA-Z0-9_-]+$

New username

Responses

Request samples

Content type
application/json
{
  • "username": "alice_new"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "alice",
  • "created_at": "2025-11-27T10:30:00Z"
}

Update password

Changes the current user's password

Authorizations:
bearerAuth
Request Body schema: application/json
required
current_password
required
string

Current password for verification

new_password
required
string >= 8 characters

New password (at least 8 characters)

Responses

Request samples

Content type
application/json
{
  • "current_password": "string",
  • "new_password": "stringst"
}

Response samples

Content type
application/json
{
  • "message": "Password updated successfully"
}

Get user information by username

Retrieves public information about a user

Authorizations:
bearerAuth
path Parameters
username
required
string

Username to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "alice",
  • "created_at": "2025-11-27T10:30:00Z"
}

Search for users

Search for users by username with pagination

Authorizations:
bearerAuth
query Parameters
q
required
string [ 2 .. 100 ] characters

Search query (minimum 2 characters)

page
integer >= 1
Default: 1

Page number

limit
integer [ 1 .. 100 ]
Default: 20

Results per page (max 100)

exclude
string

Comma-separated UUIDs to exclude (max 100)

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "total": 42,
  • "page": 1,
  • "limit": 20,
  • "total_pages": 3
}

Metadata

User metadata lookup (for JID resolution)

Get user metadata by UUID

Retrieves user metadata for JID resolution. Used to display usernames from UUIDs in XMPP messages.

Authorizations:
bearerAuth
path Parameters
userId
required
string <uuid>

User UUID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "alice",
  • "domain": "aoba.chat",
  • "displayName": "string",
  • "avatarUrl": "http://example.com"
}

Batch get user metadata

Retrieves metadata for multiple users in a single request (max 100)

Authorizations:
bearerAuth
Request Body schema: application/json
required
userIds
required
Array of strings <uuid> <= 100 items [ items <uuid > ]

List of user UUIDs (max 100)

Responses

Request samples

Content type
application/json
{
  • "userIds": [
    ]
}

Response samples

Content type
application/json
{
  • "users": [
    ]
}

Groups

Group chat management operations

Create a new group

Creates a new group chat. Creator becomes owner. Optionally invite initial members.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Group name

initial_members
Array of strings

Usernames to invite (will receive invitations)

Responses

Request samples

Content type
application/json
{
  • "name": "Engineering Team",
  • "initial_members": [
    ]
}

Response samples

Content type
application/json
{
  • "group": {
    },
  • "invitations_sent": [
    ]
}

Get group information

Retrieves information about a group including members

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group ID

Responses

Response samples

Content type
application/json
{
  • "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  • "name": "Engineering Team",
  • "owner_username": "alice",
  • "members": [
    ],
  • "created_at": "2025-11-27T11:00:00Z"
}

Delete a group

Permanently deletes a group. Only the owner can delete.

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group ID

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthorized",
  • "message": "Invalid username or password"
}

Get group admin information

Retrieves detailed group info for administration purposes

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group ID

Responses

Response samples

Content type
application/json
{
  • "group": {
    },
  • "members": [
    ],
  • "currentUserRole": "owner",
  • "ownerCount": 1,
  • "adminCount": 2
}

Leave a group

Leave a group. Owners must transfer ownership first.

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group ID

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthorized",
  • "message": "Invalid username or password"
}

Transfer group ownership

Transfer ownership to another member. Only current owner can do this.

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group ID

Request Body schema: application/json
required
newOwner
required
string

Username of new owner

Responses

Request samples

Content type
application/json
{
  • "newOwner": "string"
}

Response samples

Content type
application/json
{
  • "message": "Ownership transferred successfully",
  • "previousOwner": "alice",
  • "newOwner": "bob"
}

List group members

Get all members of a group with their roles and online status

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group ID

Responses

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "total_count": 5
}

Add a member to group

Directly add a member to a group. Only admins and owners can add members.

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group ID

Request Body schema: application/json
required
username
required
string

Username to add

role
string
Default: "member"
Enum: "admin" "member"

Role for the new member

Responses

Request samples

Content type
application/json
{
  • "username": "bob",
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "username": "alice",
  • "role": "owner",
  • "joined_at": "2019-08-24T14:15:22Z"
}

Remove a member from group

Remove a member from a group. Only admins and owners can remove members.

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group ID

username
required
string

Username to remove

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthorized",
  • "message": "Invalid username or password"
}

Update member role

Update a member's role. Only owner can change roles.

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group ID

username
required
string

Username to update

Request Body schema: application/json
required
role
required
string
Enum: "admin" "member"

New role (owner cannot be set this way)

Responses

Request samples

Content type
application/json
{
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "error": "Unauthorized",
  • "message": "Invalid username or password"
}

Invitations

Group invitation management

Invite user to group

Send a group invitation to a user. Any member can invite.

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group ID

Request Body schema: application/json
required
username
required
string

Username to invite

Responses

Request samples

Content type
application/json
{
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  • "group_name": "string",
  • "inviter_username": "string",
  • "invitee_username": "string",
  • "status": "pending",
  • "created_at": "2019-08-24T14:15:22Z",
  • "responded_at": "2019-08-24T14:15:22Z"
}

List pending invitations

Get all pending invitations for the current user

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "invitations": [
    ],
  • "count": 0
}

Accept invitation

Accept a group invitation and join the group

Authorizations:
bearerAuth
path Parameters
invitationId
required
string <uuid>

Invitation ID

Responses

Response samples

Content type
application/json
{
  • "message": "Invitation accepted",
  • "group": {
    },
  • "membership": {
    }
}

Deny invitation

Decline a group invitation

Authorizations:
bearerAuth
path Parameters
invitationId
required
string <uuid>

Invitation ID

Responses

Response samples

Content type
application/json
{
  • "message": "Invitation denied",
  • "invitation_id": "a6e6785a-3ea9-406c-b873-17eaf2ed5fc9"
}

Presence

User online/offline status

Get user presence

Get online/offline status for a user by username

Authorizations:
bearerAuth
path Parameters
username
required
string

Username

Responses

Response samples

Content type
application/json
{
  • "username": "string",
  • "status": "online",
  • "lastSeen": "2019-08-24T14:15:22Z"
}

Batch get presence by username

Get presence for multiple users by username (max 100)

Authorizations:
bearerAuth
Request Body schema: application/json
required
usernames
required
Array of strings <= 100 items

Responses

Request samples

Content type
application/json
{
  • "usernames": [
    ]
}

Response samples

Content type
application/json
{
  • "presence": {
    }
}

Get user presence by UUID

Get online/offline status for a user by UUID

Authorizations:
bearerAuth
path Parameters
userId
required
string <uuid>

User UUID

Responses

Response samples

Content type
application/json
{
  • "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
  • "status": "online",
  • "lastSeen": "2019-08-24T14:15:22Z"
}

Batch get presence by UUID

Get presence for multiple users by UUID (max 100)

Authorizations:
bearerAuth
Request Body schema: application/json
required
userIds
required
Array of strings <uuid> <= 100 items [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "userIds": [
    ]
}

Response samples

Content type
application/json
{
  • "presence": {
    }
}

Messaging

REST-based message operations

Send a message via REST

Send a message to a user or group via REST API (alternative to XMPP)

Authorizations:
bearerAuth
Request Body schema: application/json
required
to
required
string

Recipient username or group ID

content
required
string <= 10240 characters

Message content (max 10KB)

type
string
Default: "chat"
Enum: "chat" "groupchat"

Message type

Responses

Request samples

Content type
application/json
{
  • "to": "bob",
  • "content": "string",
  • "type": "chat"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "from_id": "bc3fe72f-b766-4da9-a758-da6fa33e2040",
  • "to_id": "2ecf1ac0-da2d-4b33-9f21-a773ddaca1ba",
  • "from": "string",
  • "to": "string",
  • "content": "string",
  • "type": "chat",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "status": "sent"
}

Get conversation history

Retrieve message history with pagination

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 50

Number of messages to retrieve

offset
integer >= 0
Default: 0

Offset for pagination

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "total": 0,
  • "offset": 0,
  • "limit": 0
}

System

Health and metrics endpoints

Health check

Check if the service is healthy

Responses

Prometheus metrics

Get Prometheus-formatted metrics for monitoring

Responses