# API

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

What's documented here? Any endpoint that is implemented to some degree. If something here is implemented but not yet tested it will still be listed here but just marked with **UNTESTED**.

**NOTE**: Unless otherwise stated endpoints take their parameters via a JSON body. Even if it's a GET request freechat uses HTTP bodies like mad. At some point this might change however it's primarily because it makes more semantic sense to query data using a GET in some cases.


## Authentication

Required for basically every endpoint is: 

1. `id` - the server assigned user id

2. `secret` - the server assigned 

**A word on permissions**: while you should have the permissions assigned to you cached somewhere server does a check for your permissions on the instance anyway so there's no need to supply this to the server.

### Obtaining ad id + secret

For instance owners you can use the command-line option `-c` or `--create-owner` to create an account with owner level permissions. It does without saying(except here) that this should only be used for the _most important people to the instance_ **the owners**.

## Invites

```
{
	id: i64,
	expires: bool,
	uses: i32 | null
}
```

### Fields

- id : timestamp which doubles as the invite's expire date

- expires : Boolean value which tells us whether or not to ignore the id(timestamp) expire value.

- uses : Either `i32` or `null`. Counts how many times the invite can be used. Null means we ignore this field: by default this field should be set to null, as invites expire due to their age first.

### Invites Endpoints

* `GET /invites/create` 

Basic users can create invites which expire and optionally have a use limit. More privileged users can create invites that do not expire. Both types of users can create invites which have no use limit.

* `GET /invite/<code>`

Allows a user that isn't part of the server to join. Updates the invite data accordingly assuming everything is valid.

On success it responds to the client with the following user structure.

```
{
	id: u64,
	name: String,
	secret: String,
	joindate: i64,
	status: i32,
	permissions: u64
}
```

The status fields have the following acceptable values: 

* Online := 0

* Offline:= 1

* Away := 2

* Do Not Disturb := 3

__Secret__:  Base64 encoded string, as its generated by a cryptographically random byte string 64 bytes long. All characters are URL safe. The string itself is hashed and salted into the database and checked on each attempted use.

## Channels

```
{
	id: u64,
	name: String,
	description: String | null,
	kind: i32 
}
```

### Fields

* id : ...

* name : ...

* description : can be either null or some string

* kind : `Voice Channels := 1` and `Text Channels := 2`

### Channel Endpoints


* `GET /channels/list`

Returns: Full list of channels in no particular order


## Messaging

**UNTESTED + UNIMPLEMENTED**: route is a work in progress

* `GET /message/recent`

**Requires Parameter**: from<i64>

Pull up to the last 72 hours of messages, most clients should aim for less however, especially for servers that are more active as this request could end up taking forever or simply returns way too much data.


**UNTESTED + UNIMPLEMENTED**: route is a work in progress

* `GET /message/range`

**Requires Parameter**: from<i64>

**Requires Parameter**: to<i64>

**On success**: A json encoded list of messages sorted by the order they were received by the server

**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 or greater.

* `POST /admin/setpermissions`

**Requires Parameter**: target-id

**Requires Permissions**: Admin

Sets the permissions for that user assuming they are not also an admin


* `POST /owner/newadmin`

**Requires Parameter**: target-id

**Requires Permissions**: Owner

Gives that user admin level permissions, does nothing with other owners
