List of API endpoints

Some endpoints which may return a large number of results use Pagination. These are marked with [P] below.

See Authentication for details on how to authenticate when using the API.

See Types of JSON object for the structure of objects returned by the API.

Account-related endpoints

GET /accounts/signups

Check if signups are open.

Returns a JSON object containing:

• signups_open (boolean)

POST /acounts/new

Parameters (JSON body):

• id (int or string representing int, a Discord ID)

• name (string)

• discriminator (string)

• avatar_url (optional string)

• team (optional int, the ID of the team)

• permissions (optional int, default 0)

Returns an Account object, a 409 error if the id has already been registered, or a 403 error if signups are closed.

Requires the manage_account_details permission. Additionally, see Permissions for what permissions you are allowed to grant.

[P] GET /accounts/search

Parameters (URL query string):

• q (optional string, to search for)

• team (optional int, the ID of a team)

If team is passed, only returns accounts from that team.

Returns a paginated list of Account objects matching the query (see Pagination).

PATCH /account/{account}

Parameters (dynamic URL path):

• account (int, the ID of the account to get)

Parameters (JSON body):

• name (optional string)

• discriminator (optional string)

• avatar_url (optional string)

• team (optional int, the ID of the team to move the user to)

• grant_permissions (optional int, permissions to grant the user)

• revoke_permissions (optional int, permissions to revoke from the user)

• discord_token (optional string, Discord token to fetch user data from)

Note that team can also be 0, which indicates that the user should be removed from their team.

Returns a 422 error if the account was not found (not a 404 error).

If discord_token was passed but was invalid or didn’t have the indentify scope, a 422 error is returned. If the token was valid but was for the wrong account ID, a 403 error is returned.

Returns an Account object if successful.

Different parameters require different permissions:

Parameter	Permission
name	manage_account_details
discriminator	manage_account_details
avatar_url	manage_account_details
team	manage_account_teams *1
grant_permissions	See Permissions
revoke_permissions	See Permissions
discord_token	None

^*1 You can also remove a user from a team if you are a member of that team and have the manage_own_team permission. You can also add yourself to a team.

GET /account/{account}

Parameters (dynamic URL path):

• account (int, the ID of the account to get)

Returns an Account object if successful.

Returns a 422 error if the account was not found (not a 404 error).

DELETE /account/{account}

Parameters (dynamic URL path):

• account (int, the ID of the account to get)

Returns 204 (no content) if successful.

Returns a 422 error if the account was not found (not a 404 error).

Requires the manage_account_details permission, or being authenticated for this account.

Team-related endpoints

POST /teams/new

Parameters (JSON body):

• name (string)

Returns a new Team object. Requires the manage_teams permission.

[P] GET /teams/search

Parameters (URL query string):

• q (optional string)

Returns a paginated list of Team objects (see Pagination). The optional q parameter allows you to filter teams by searching in their name.

GET /team/{team}

Parameters (dynamic URL path):

• team (int, ID of the team to get)

Returns a Team object, or a 422 error if not found (not a 404 error).

PATCH /team/{team}

Parameters (dynamic URL path):

• team (int, ID of the team to edit)

Parameters (JSON body):

• name (string, the new name of the team)

Returns a Team object if successful, or a 422 error if not found (not a 404 error).

Requires the manage_teams permission, or the manage_own_team permission and authentication with an account that is a member of the specified team.

DELETE /team/{team}

Parameters (dynamic URL path):

• team (int, ID of the team to delete)

Returns 204 (no content) if successful, or a 422 error if not found (not a 404 error).

Award-related endpoints

POST /awards/new

Creates a new award. An award is given to a selection of users but also to their team. Requires the manage_awards permission.

Parameters (JSON body):

• title (string)

• image_url (string)

• team (int, the ID of a team)

• accounts (list of string s, the IDs of accounts)

team should (but is not required to) refer to a team that all the accounts are part of.

Returns an Award object.

PATCH /award/{award}

Updates an existing award. Requires the manage_awards permission.

Parameters (dynamic URL path):

• award (int, the ID of the award to edit)

Parameters (JSON body):

• title (optional string)

• image_url (optional string)

• team (optional int, the ID of a team)

Returns an Award object, or a 422 error if not found (not a 404 error).

GET /award/{award}

Get the details of an award.

Parameters (dynamic URL path):

• award (int, the ID of the award to get)

Returns:

• award (an ``Award object)

• awardees (a list of Account objects)

• team (optional Team object)

Instead returns a 422 error if not found (not a 404 error).

DELETE /award/{award}

Remove an award. Requires the manage_awards permission.

Parameters (dynamic URL path):

• award (int, the ID of the award to delete)

Returns 204 (no content) if successful, or a 422 error if not found (not a 404 error).

PUT /account/{account}/award/{award}

Give an existing award to a new user. Requires the manage_awards permission.

Parameters (dynamic URL path):

• account (string, the ID of the account to assign the award to)

• award (int, the ID of the award to assign)

Returns 201 with no content if successful, 208 if the user already had the award, or 422 if the user or award was not found.

DELETE /account/{account}/award/{award}

Remove an award from a user. Requires the manage_awards permission.

Parameters (dynamic URL path):

• account (string, the ID of the account to remove the award from)

• award (int, the ID of the award to remove)

Returns 204 (no content) if successful, 404 if the user did not have the award, or 422 if the user or award was not found.

Callback-related endpoints

PUT /callback/{event}

Create a callback for a specified event type. Requires an app token.

Parameters (dynamic URL path):

• event (string, see Callbacks for event types)

Parameters (JSON body):

• url (string, the URL to recieve events)

• secret (string, a secret to use when sending events)

Returns a Callback object. If a callback already exists for this event type, this endpoint will override it. If the event type is invalid, returns a 422 error.

DELETE /callback/{event}

Delete the callback for a specified event type. Requires an app token.

Parameters (dynamic URL path):

• event (string, the event type to delete the callback for)

Returns 204 (no content) if successful, a 422 error if the event type is invalid, or 404 error if there is no callback registered for the event type.

GET /callback/{event}

Get details on a registered callback. Requires an app token.

Parameters (dynamic URL path):

• event (string, see Callbacks for event types)

Returns a Callback object if successful, a 422 error if the event type is invalid, or 404 error if there is no callback registered for the event type.

GET /callbacks

Get all registered callbacks for the authenticated app. Requires an app token.

Returns:

• callbacks (an object where the keys are event types and the values are the registered callback URLs)

Authentication-related endpoints

POST /auth/discord

Creates a session from a Discord user token (obtainable with Discord OAuth2).

Parameters (JSON body):

• token (string, the Discord token)

Returns a Session object. If the token was valid but the account was not found, creates the account, or returns a 403 error if signups are closed. Returns a 401 error if the token was invalid Note that the token must be authorised for the identify scope.

POST /auth/create_session

Parameters (JSON body):

• account (int, the ID of the account to get)

Returns a Session object, or a 422 error if the account was not found (not a 404 error).

Requires the authenticate_users permission, which only apps can have.

POST /auth/reset_token

Reset the token used to authenticate. Returns an App object with a token present if an app token was used to authenticate, or a Session object if a user token was used to authenticate.

Returns a 401 error if no authentication was used.

GET /auth/me

Returns either an App object (with no token present) or an Account object, depending on what token was used to authenticate.

Returns a 401 error if no authentication was used.