Skip to content

Latest commit

 

History

History
514 lines (393 loc) · 9.93 KB

DOCUMENTATION.md

File metadata and controls

514 lines (393 loc) · 9.93 KB
Raw

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: [
                {
                    deletion_server_id: i64,
                    deleted_message_id: i64
                },
                {
                    ...
                }
            ]
            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
        },
        ...
    ]
}

POST /delete_messages

Header Required Notes
Authorization Yes Basic OR Moderator
Room Yes

Deletes the messages with the given IDs from the server. The requesting user must either be the sender of the messages or have moderation permission.

Expected body:

{
    ids: [ 0, 1, 2, ... ], // the server IDs of the messages to delete
}

Response:

{
    status_code: u16
}

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: [
        {
            deletion_server_id: i64,
            deleted_message_id: i64
        },
        {
            ...
        }
    ]
}

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
}

POST /ban_and_delete_all

Header Required Notes
Authorization Yes Moderator
Room Yes

Ban the given public key from the server and delete all messages sent by them.

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
}