Communication API

Rules

No Spamming / abuse of the API.
Abuse will lead to perma ban.

You MUST Encrypt all sensitive data before sending it through the API.
No data will be encrypted server side

Two types of connexions exist: anonymous and registered.
Anonymous connections are temporary and will be deleted after 3 minutes of inactivity.
Registered connections are persistent and will remain active until explicitly deleted or inactive for 3 months.
Registered connections require a password for authentication.

Deletion is permanent and includes all messages (received and sent).

Endpoints

All api endpoints are under the /api/ path.

Endpoints tagged AUTH require authentication.
Credentials are provided via the useruuid and token headers (the user_uuid and connect_token returned by register or login).

All response will be encapsulated in JSON format in a data object with request information.
For example:

{
    "request_id": "example_request_id",
    "status": "success",
    "message": "Request processed successfully.",
    "data": {
        "key": "value"
    }
}

POST

/register.php

Registers a new user.
Password is optional for anonymous registration.

Parameters

username: The desired username for the new user. Must be unique (case-insensitive, otherwise a 409 error is returned). Alphanumeric only, at least 5 characters; usernames containing "admin", "modo" or "moderator" are refused.
password: The desired password for the new user (at least 8 characters).

optional

{
    "username": "exampleUser",
    "password": "example_password"
}

Response

user_uuid: The unique identifier for the newly registered user. (UUIDv7) username: The username of the newly registered user. anonymous: Boolean indicating if the user is anonymous. connect_token: The connect token for the newly registered user.

{
    "user_uuid": "01a15408-366e-78cd-8ef9-63acc568509d",
    "username": "exampleUser",
    "anonymous": false,
    "connect_token": "example_connect_token",
    "registered_at": "2024-06-05T12:34:56Z",
    "last_activity_at": "2024-06-05T12:34:56Z"
}

POST

/login

Logs in a registered user.
Returns the user uuid and connect token to use in the useruuid and token headers of authenticated endpoints.

Parameters

username: The username of the user.
password: The password of the user.

{
    "username": "exampleUser",
    "password": "example_password"
}

Response

user_uuid: The unique identifier of the user.
connect_token: The connect token of the user.

{
    "user_uuid": "01a15408-366e-78cd-8ef9-63acc568509d",
    "connect_token": "example_connect_token"
}

GET

/users.php

Get a list of users.
Without parameters all active users will be returned.
With the `username` parameter, only users matching the specified username will be returned.
With the `user_uuid` parameter, only the user with the specified UUID will be returned.

Parameters

username: Search by username.

optional

user_uuid: Search by user UUID.

optional

?username=exampleUser
?user_uuid=01a15408-366e-78cd-8ef9-63acc568509d

Response

user_uuid: The unique identifier for the user. username: The username of the user. anonymous: Boolean indicating if the user is anonymous.

{
    "user_uuid": "01a15408-366e-78cd-8ef9-63acc568509d",
    "username": "exampleUser",
    "anonymous": false
}

POST

AUTH

/send.php

Sends a message to another user.
Encrypt the message before sending it; the server does not encrypt messages.
The message must be no longer than 1500 characters.

Parameters

recipient_uuid: The UUID of the user who will receive the message.
message: The encrypted message to send (maximum 1500 characters).

{
    "recipient_uuid": "01a15408-366e-78cd-8ef9-63acc568509d",
    "message": "encrypted_message"
}

GET

AUTH

/unreads.php

Get the number of unread messages, grouped by sender user.

Response

total: Total number of unread messages.
unreads: List of senders with their unread message count.
user_uuid: The unique identifier of the sender.
count: Number of unread messages from this user.

{
    "total": 3,
    "unreads": [
        {
            "user_uuid": "01a15408-366e-78cd-8ef9-63acc568509d",
            "count": 3
        }
        ...
    ]
}

GET

AUTH

/conversations.php

List the existing conversations of the authenticated user, one per other user, most recent first. Each entry contains the last message of the conversation. This endpoint does not mark messages as read.

Response

conversations: List of conversations.
user_uuid: The unique identifier of the other user.
username: The username of the other user.
anonymous: Whether the other user is anonymous.
unread: Number of unread messages received from this user.
last_message: Last message (sent or received) with message_uuid, timestamp, sender and message.

{
    "conversations": [
        {
            "user_uuid": "01a15408-366e-78cd-8ef9-63acc568509d",
            "username": "alice",
            "anonymous": false,
            "unread": 2,
            "last_message": {
                "message_uuid": "01a15408-366e-78cd-8ef9-63acc568509e",
                "timestamp": "2026-10-26T15:12:16+00:00",
                "sender": "01a15408-366e-78cd-8ef9-63acc568509d",
                "message": "Hello"
            }
        }
        ...
    ]
}

GET

AUTH

/conv.php

Get the last x messages of the conversation with another user (sent and received).
By default the last 10 messages are returned.

Parameters

user_uuid: The UUID of the other user in the conversation.
x: Number of messages to return (default: 10, maximum: 500).

optional

?user_uuid=01a15408-366e-78cd-8ef9-63acc568509e&x=20

Response

message_uuid: The unique identifier of the message. (UUIDv7)
timestamp: Date and time the message was sent.
sender: The user_uuid of the sender.
message: The (encrypted) message content.

[
    {
        "message_uuid": "01a15408-366e-78cd-8ef9-63acc568509d",
        "timestamp": "2026-10-19T15:05:52+02:00",
        "sender": "01a15408-366e-78cd-8ef9-63acc568509e",
        "message": "encrypted_message"
    }
    ...
]

Documentation:

Rules

Endpoints