# Encore API

All API routes are prefixed with `/api/v{x}` where `{x}` is the API version. This version is currently `1`.

## API Versions

| Version | Active |
|---------|--------|
| 1 | Yes |

## Rate Limiting

Routes have dynamic ratelimits that may change without warning and can differ by hub or user. The system used for ratelimiting is detailed below:

- `RateLimit-Limit: X` - The maximum number of requests per period.
- `RateLimit-Period: X` - The period of the rate limit in seconds.
- `RateLimit-Remaining: X` - The number of requests remaining in the current period.
- `RateLimit-Reset: X` - The Unix timestamp at which the current period ends.

## Authentication

Authentication is handled by providing an `Authorization` header in the format `Authorization: Encore {token}`. Tokens are provided by the `GET /auth/login` route. The token is a JWT with the following data:

| Field | Type | Description |
|-------|-----------|---------------------------------------------------------------|
| `u` | `ID` | The token's user's ID. |
| `e` | `integer` | The Unix timestamp in seconds at which the token will expire. |
| `t` | `integer` | The Unix timestamp in seconds at which the token was created. |

## Objects

Many objects have a few common attributes, unless noted otherwise:

- Names must match the RegEx pattern `^[a-zA-Z0-9_-]{1,255}$`
- ID types will be provided as an integer, but will be converted by the API to a string if the `Encore-ID-Type` header is set to `string`.
- `icon_url` is an arbitrary HTTPS URL for an image to be displayed in the UI. In the client all icons are proxied through Encore to protect user privacy.

IDs are snowflakes which are guaranteed to be unique. They follow a similar structure to Discord's snowflake IDs:

- 50 bits - Unix timestamp in milliseconds
- 6 bits - worker ID
- 8 bits - increment

### User

| Field | Type | Description |
|------------|-----------------|----------------------------------------------------------|
| `id` | `ID` | The user's ID. |
| `name` | `string(2,32)` | The user's username. Must match `^[a-zA-Z0-9_-]{2,32}$`. |
| `disc` | `string(4)` | The user's discriminator. |
| `icon_url` | `string(1,255)` | The user's icon URL. |
| `flags` | `[]string` | The user's flags. |

### Text Channel

| Field | Type | Description |
|---------|-----------------|-------------------------------------------------|
| `id` | `ID` | The channel's ID. |
| `type` | `literal[1]` | The channel's type. Always 1 for text channels. |
| `name` | `string(1,255)` | The channel's name. |
| `flags` | `[]string` | The channel's flags. |

### Member

Note: members are currently essentially the same as users, but are provided for future compatibility.

| Field | Type | Description |
|--------|--------|--------------------|
| `user` | `User` | The member's User. |

### Hub

| Field | Type | Description |
|------------|------------------|---------------------------------------------------|
| `id` | `ID` | The hub's ID. |
| `owner` | `User` | The hub's owner. |
| `name` | `string(1,255)` | The hub's name. |
| `icon_url` | `string(1,255)` | The hub's icon URL. |
| `channels` | `[]Text Channel` | The hub's channels. Currently only Text Channels. |
| `members` | `[]Member` | The hub's members. |
| `flags` | `[]string` | The hub's flags. |

### Message

| Field | Type | Description |
|--------------|------------------|------------------------------------|
| `id` | `ID` | The message's ID. |
| `channel_id` | `ID` | The message's parent channel's ID. |
| `hub_id` | `ID` | The message's parent hub's ID. |
| `author_id` | `ID` | The message's author's ID. |
| `text` | `string(1,2048)` | The message's text. |
| `flags` | `[]string` | The message's flags. |

## Endpoints

### Meta Endpoints

#### `GET /auth/login`

This endpoint accepts a code from the GitHub OAuth flow and returns an Encore token which can be used to perform API requests.

#### `DELETE /auth`

This endpoint deletes the current user's token. Any requests performed on the same token after this request will fail.

### User Endpoints

#### `GET /users/:user_id`

This endpoint returns a `User` object for the given user ID. If the user is not found a 404 status will be returned.

#### `PATCH /users/:user_id`

This endpoint updates the user's details and returns a `User` object. This can only be performed by the user being updated or by a user with the `PLATFORM_ADMIN` user flag. If the user is not found a 404 status will be returned.

Request JSON Body:

| Field | Type | Description |
|------------|-----------------|----------------------------------------------------------|
| `name` | `string(2,32)` | The user's username. Must match `^[a-zA-Z0-9_-]{2,32}$`. |
| `disc` | `string(4)` | The user's discriminator. (`PLATFORM_ADMIN` only.) |
| `icon_url` | `string(1,255)` | The user's icon URL. |
| `flags` | `[]string` | The user's flags. (`PLATFORM_ADMIN` only.) |

#### `DELETE /users/:user_id`

This endpoint deletes the user. This can only be performed by the user being deleted or by a user with the `PLATFORM_ADMIN` user flag. If the user is not found a 404 status will be returned.

### Hub Endpoints

#### `POST /hubs`

This endpoint creates a new hub and returns a `Hub` object.

Request JSON Body:

| Field | Type | Description |
|---------|-----------------|-------------------------------------------|
| `name` | `string(1,255)` | The hub's name. |
| `flags` | `[]string` | The hub's flags. (`PLATFORM_ADMIN` only.) |

#### `GET /hubs/:hub_id`

This endpoint returns a `Hub` object for the given hub ID. If the hub is not found a 404 status will be returned.

#### `PATCH /hubs/:hub_id`

This endpoint updates the hub's details and returns a `Hub` object. This can only be performed by the hub's owner or by a user with the `PLATFORM_ADMIN` user flag. If the hub is not found a 404 status will be returned.

Request JSON Body:

| Field | Type | Description |
|---------|-----------------|-------------------------------------------|
| `name` | `string(1,255)` | The hub's name. |
| `flags` | `[]string` | The hub's flags. (`PLATFORM_ADMIN` only.) |

#### `DELETE /hubs/:hub_id`

This endpoint deletes the hub. This can only be performed by the hub's owner or by a user with the `PLATFORM_ADMIN` user flag. If the hub is not found a 404 status will be returned.

### Channel Endpoints

All channel endpoints must be performed by a user either in the same hub as the target channel or with the `PLATFORM_ADMIN` user flag.

#### `POST /hubs/:hub_id/channels`

This endpoint creates a new channel and returns a `Text Channel` object.

Request JSON Body:

| Field | Type | Description |
|---------|-----------------|-------------------------------------------------|
| `type` | `literal[1]` | The channel's type. Always 1 for text channels. |
| `name` | `string(1,255)` | The channel's name. |
| `flags` | `[]string` | The channel's flags. (`PLATFORM_ADMIN` only.) |

#### `GET /channels/:channel_id`

This endpoint returns a `Text Channel` object for the given channel ID. If the channel is not found a 404 status will be returned.

#### `PATCH /channels/:channel_id`

This endpoint updates the channel's details and returns a `Text Channel` object. This can only be performed by the channel's parent hub's owner or by a user with the `PLATFORM_ADMIN` user flag. If the channel is not found a 404 status will be returned.

Request JSON Body:

| Field | Type | Description |
|---------|-----------------|-----------------------------------------------|
| `name` | `string(1,255)` | The channel's name. |
| `flags` | `[]string` | The channel's flags. (`PLATFORM_ADMIN` only.) |

#### `DELETE /channels/:channel_id`

This endpoint deletes the channel. This can only be performed by the channel's parent hub's owner or by a user with the `PLATFORM_ADMIN` user flag. If the channel is not found a 404 status will be returned.

#### `POST /channels/:channel_id/messages`

This endpoint creates a new message and returns a `Message` object.

Request JSON Body:

| Field | Type | Description |
|---------|------------------|-----------------------------------------------|
| `text` | `string(1,2048)` | The message's text. |
| `flags` | `[]string` | The message's flags. (`PLATFORM_ADMIN` only.) |

#### `GET /channels/:channel_id/messages/:message_id`

This endpoint returns a `Message` object for the given message ID. If the message is not found a 404 status will be returned.

#### `PATCH /channels/:channel_id/messages/:message_id`

This endpoint updates the message's text and returns a `Message` object. This can only be performed by the message's author or by a user with the `PLATFORM_ADMIN` user flag. If the message is not found a 404 status will be returned.

Request JSON Body:

| Field | Type | Description |
|---------|------------------|-----------------------------------------------|
| `text` | `string(1,2048)` | The message's text. |
| `flags` | `[]string` | The message's flags. (`PLATFORM_ADMIN` only.) |

#### `DELETE /channels/:channel_id/messages/:message_id`

This endpoint deletes the message. This can only be performed by the message's author, the hub's owner, or by a user with the `PLATFORM_ADMIN` user flag. If the message is not found a 404 status will be returned.