freechat/docs/api.md

API

Voice connections are not yet authored as they are far from being implemented

Auth Routes

Logging in

Authenticated routes require a session key which this route provides, given a previously invited user's credentials

/auth/login

Parameters:

• id

  User id provided by the instance

• secret

  API key provided by the instance

Return:

• api-key

  Binary string base64 encoded. This encoding is not to be undone or further authentication will fail.

• expiration

  Unix time stamp dictating when this key should be deleted server side. Though the server may delete the key later than this time-stamp the client can request a new token via /auth/login or /auth/refresh.

Leaving an instance

Parameters

• id User id provided by the instance
• secret API key provided by the instance

Return:

• On success: A simple HTTP 200 response; empty body.

• On failure: An HTTP 400 Bad Request response; which parameter is wrong is not specified to avoid enumeration style attacks.

Channels

/channels/list/voice
/channels/list/text

Return: List of struct::Channels owned by the server voice/text

/channels/voice/

Return: List of struct::Members in that given channel

Messaging

/message/recent/<channel>

Parameters:

• from::UnixTimestamp

DateTime from which to pull messages. Max value on this route can be no more than 72 hours in the past. To pull further messages you will need to use the /message/range route.

/message/range

Parameters:

• start::UnixTimestamp

• end::UnixTimestamp

On this route instances by default allow up to 1 week worth of range. Note of course that the closer a client gets to this maximum the longer it will take to load. Some instances may be configured to only return a certain number of messages as well so it is worthwhile to check the bounds of the messages a client receives.

On success: A json encoded list of struct::Message will be returned with a 200 Ok

On paramter failure: HTTP 400 Bad request

On server error: HTTP 500 Internal Server Error

Administrative Instance Routes

The following routes can only be used by logged in users who have badges with administrative permissions.

/admin/setperm

Parameter

• permission

The permission provided is applied internally as a bit mask, a full list of permissions can be found under the permissions sections.

Permissions

Below is a list of currently supported permissions which badges can have. Keep in mind the size of these badges is 64 bits long and is stored internally as unsigned 64 bit integers.