session-open-group-server/DOCUMENTATION.md

All endpoints return the status code in the response body because that's the only way to propagate the status code back to the client when using onion requests.

Endpoints

GET /rooms/:room_id

Header	Required	Notes
Authorization	No
Room	No

Returns information about the room with the given ID.

Response:

{
    status_code: u16,
    room: {
        id: String,
        name: String
    }
}

GET /rooms

Header	Required	Notes
Authorization	No
Room	No

Returns a list of all rooms on the server.

Response:

{
    status_code: u16,
    rooms: [
        {
            id: String,
            name: String
        },
        ...
    ]
}

POST /files

Header	Required	Notes
Authorization	Yes	Basic
Room	Yes

Store a file on the server.

Expected body:

{
    file: String // base64 encoded data
}

Response:

{
    status_code: u16
}

POST /rooms/:room_id/image

Header	Required	Notes
Authorization	Yes	Moderator
Room	No

Set the image for a room.

Expected body:

{
    file: String // base64 encoded data
}

Response:

{
    status_code: u16,
    room_id: String
}

GET /files/:file_id

Header	Required	Notes
Authorization	Yes	Basic
Room	Yes

Get a file from the server.

Response:

{
    status_code: u16,
    result: String // base64 encoded data
}

GET /rooms/:room_id/image

Header	Required	Notes
Authorization	No
Room	No

Returns the preview image for the given group.

Response:

{
    status_code: u16,
    result: String // base64 encoded data
}

GET /auth_token_challenge?public_key=string

Header	Required	Notes
Authorization	No
Room	Yes

Get an auth token challenge. The requesting user generates a symmetric key from the ephemeral public key returned by the server and their private key, which can be used to decrypt the ciphertext and get the auth token.

Response:

{
    status_code: u16,
    challenge: {
        ciphertext: String, // base64 encoded data
        ephemeral_public_key: String // base64 encoded data
    }
}

POST /claim_auth_token

Header	Required	Notes
Authorization	Yes	Basic
Room	Yes

Claim the auth token in the Authorization header.

Expected body:

{
    public_key: String
}

Response:

{
    status_code: u16
}

DELETE /auth_token

Header	Required	Notes
Authorization	Yes	Basic
Room	Yes

Delete the auth token in the Authorization header.

Response:

{
    status_code: u16
}

POST /compact_poll

Header	Required	Notes
Authorization	No	Authorization is handled on a room-by-room basis in the request body
Room	No

Poll for new messages, new deletions and the current moderator list for multiple rooms all in one request.

Expected body:

{
    requests: [
        {
            room_id: String,
            auth_token: String,
            from_deletion_server_id: Option<i64>,
            from_message_server_id: Option<i64>
        },
        {
            ...
        }
    ]
}

Response:

{
    status_code: u16
    results: [
        {
            room_id: String,
            status_code: u16,
            deletions: [ 0, 1, 2, ... ]
            messages: [
                {
                    server_id: i64,
                    public_key: String,
                    timestamp: i64,
                    data: String,
                    signature: String
                },
                {
                    ...
                }
            ]
            moderators: [ "public_key_0", "public_key_1", "public_key_2", ... ]
        },
        {
            ...
        }
    ]
}

POST /messages

Header	Required	Notes
Authorization	Yes	Basic
Room	Yes

Store the given message on the server.

Expected body:

{
    public_key: Option<String>, // the public key of the sender
    timestamp: i64, // the sent timestamp of the message
    data: String, // the serialized protobuf
    signature: String // the base64 encoded message signature
}

Response:

{
    status_code: u16
    message: {
        server_id: String,
        public_key: Option<String>
        timestamp: i64
        data: String
        signature: String
    }
}

GET /messages?from_server_id=i64&limit=u16

Header	Required	Notes
Authorization	Yes	Basic
Room	Yes

Get messages from the server. If from_server_id is set only messages stored after that server ID are returned (limited to a maximum of 256 messages). Otherwise, if limit is set, the last limit messages stored on the server are returned (limited to a maximum of 256 messages).

Response:

{
    status_code: u16,
    messages: [
        {
            server_id: String,
            public_key: Option<String>, // the public key of the sender
            timestamp: i64, // the sent timestamp of the message
            data: String, // the serialized protobuf
            signature: String // the base64 encoded message signature
        },
        ...
    ]
}

DELETE /messages/:message_id

Header	Required	Notes
Authorization	Yes	Basic OR Moderator
Room	Yes

Delete the message with the given ID from the server. The requesting user must either be the sender of the message or have moderation permission.

Response:

{
    status_code: u16
}

GET /deleted_messages?from_server_id=i64&limit=u16

Header	Required	Notes
Authorization	Yes	Basic
Room	Yes

Get deleted messages from the server. If from_server_id is set only deletions that happened after that server ID are returned (limited to a maximum of 256 deletions). Otherwise, if limit is set, the last limit deletions stored on the server are returned (limited to a maximum of 256 deletions).

Response:

{
    status_code: u16,
    ids: [ 0, 1, 2, ... ] // the server IDs of the deleted messages
}

GET /moderators

Header	Required	Notes
Authorization	Yes	Basic
Room	Yes

Get the full list of moderators.

Response:

{
    status_code: u16,
    moderators: [ "public_key_0", "public_key_1", "public_key_2", ... ]
}

POST /block_list

Header	Required	Notes
Authorization	Yes	Moderator
Room	Yes

Ban the given public key from the server.

Expected body:

{
    public_key: String
}

Response:

{
    status_code: u16
}

DELETE /block_list/:public_key

Header	Required	Notes
Authorization	Yes	Moderator
Room	Yes

Unban the given public key from the server.

Response:

{
    status_code: u16
}

GET /block_list

Header	Required	Notes
Authorization	Yes	Basic
Room	Yes

Get the full list of banned public_keys.

Response:

{
    status_code: u16,
    moderators: [ "public_key_0", "public_key_1", "public_key_2", ... ]
}

GET /member_count

Header	Required	Notes
Authorization	Yes	Basic
Room	Yes

Get the member count for the given room.

Response:

{
    status_code: u16,
    member_count: usize
}