Introduction

Welcome to the Equion API documentation. This documentation is for Equion API v1.

Warning: This is a work in progress, and all API calls are subject to change.

Core API
HTTP-Only API
- Files
WebSocket-Only API
- General
- Voice
- Events
Message Encoding

Core API

All API calls in this section can either be POSTed to https://example.com/api/{command} or be sent through WebSocket to wss://example.com/ws with the additional command parameter.

Authentication API

Asserts that the username and password combination are valid, then returns a token that can be used to authenticate future requests. The token does not expire, but can be invalidated with v1/logout.

Input:

{ "username": "", "password": "" }

Output:

{ "success": true, "token": "", "uid": "" }

Signs up a user with the given details. Further customisation should be done through the v1/updateUser endpoint. The user will be automatically logged in, so a token will be returned, along with the new user's ID. If the user name already exists, an error will occur.

Input:

{ "username": "", "password": "", "displayName": "", "email": "" }

Output:

{ "success": true, "token": "", "uid": "" }

`v1/logout`: Logout and invalidate token

Logs out the user and invalidates the token.

Input:

{ "token": "" }

Output:

{ "success": true }

`v1/validateToken`: Validate token

Asserts that the token is valid, and if so, returns the user's ID. Used for restoring sessions.

Input:

{ "token": "" }

Output:

{
  "success": true,
  "uid": ""
}

User API

`v1/user`: Get user details

Gets details for the user with the given ID. This endpoint does not require authentication. The user's email is currently returned, but this is likely to change in the future.

Input:

{ "uid": "" }

Output:

{
  "success": true,
  "user": {
    "uid": "",
    "username": "",
    "displayName": "",
    "email": "",
    "image?": "",
    "bio?": "",
    "online": true
  }
}

`v1/updateUser`: Update user details

Updates the current user's details. This endpoint requires authentication to identify and authenticate the user. All fields apart from token are optional, and only the fields specified will be updated.

Input:

{
  "token": "",
  "displayName?": "",
  "email?": "",
  "bio?": ""
}

Output:

{ "success": true }

Sets and Subsets API

`v1/sets`: Get all sets for the user

Returns all of the current user's sets, in no particular order.

Input:

{ "token": "" }

Output:

{
  "success": true,
  "sets": [
    {
      "id": "",
      "name": "",
      "icon": "",
      "admin": false,
      "subsets": [
        {
          "id": "",
          "name": "",
        }
      ],
      "members": [
        {
          "uid": "",
          "username": "",
          "displayName": "",
          "email": "",
          "image?": "",
          "bio?": "",
          "online": true
        }
      ],
      "voiceMembers": [
        {
          "peerId": "",
          "user": {
            "uid": "",
            "username": "",
            "displayName": "",
            "email": "",
            "image?": "",
            "bio?": "",
            "online": true
          }
        }
      ]
    }
  ]
}

`v1/set`: Get set details

Gets details for a specific set. This endpoint requires authentication, and will return an error if the user is not a member of the set.

Input:

{ "token": "", "id": "" }

Output:

{
  "success": true,
  "set": {
    "id": "",
    "name": "",
    "icon": "",
    "admin": false,
    "subsets": [
      {
        "id": "",
        "name": "",
      }
    ],
    "members": [
      {
        "uid": "",
        "username": "",
        "displayName": "",
        "email": "",
        "image?": "",
        "bio?": "",
        "online": true
      }
    ],
    "voiceMembers": [
      {
        "peerId": "",
        "user": {
          "uid": "",
          "username": "",
          "displayName": "",
          "email": "",
          "image?": "",
          "bio?": "",
          "online": true
        }
      }
    ]
  }
}

`v1/createSet`: Create a new set

Creates a new set with the given name, and icon if supplied. Returns the ID of the new set. The authenticated user will automatically become a member of the set, and will also be given administrative privileges over the set.

Input:

{
  "token": "",
  "name": "",
  "icon?": "",
}

Output:

{ "success": true, "id": "" }

`v1/createSubset`: Create a new subset

Creates a new subset of the given set with the given name. Returns the ID of the new subset.

Input:

{
  "token": "",
  "set": "",
  "name": "",
}

Output:

{ "success": true, "id": "" }

`v1/invites`: Get all invites for a set

Returns all the invites for the given set. Requires the user to be a member of the set.

Input:

{
  "token": "",
  "set": "",
}

Output:

{
  "success": true,
  "invites": [
    {
      "id": "",
      "setId": "",
      "setName": "",
      "setIcon": "",
      "code": "",
      "created": 0, // UNIX timestamp
      "expires": 0, // UNIX timestamp
      "uses": 0
    }
  ]
}

`v1/invite`: Get information about a specific invite

Returns information about the specific invite. Does not require authentication.

Input:

{ "code": "" }

Output:

{
  "success": true,
  "invite": {
    "id": "",
    "setId": "",
    "setName": "",
    "setIcon": "",
    "code": "",
    "created": 0, // UNIX timestamp
    "expires": 0, // UNIX timestamp
    "uses": 0
  }
}

`v1/createInvite`: Create a new invite code

Creates a new invite code for the given set. Requires the user to be an administrator of the set. If a custom code is specified, the user must subscribe to Equion Diffontial (maybe coming soon?) to use it.

Input:

{
  "token": "",
  "set": "",
  "duration?": 0, // minutes
  "code?": "",
}

Output:

{ "success": true, "code": "" }

`v1/revokeInvite`: Revoke an invite code

Revokes an invite for the given set. Requires the user to be an administrator of the set.

Input:

{
  "token": "",
  "set": "",
  "invite": "",
}

Output:

{ "success": true }

`v1/joinSet`: Join a set

Joins the authenticated user to the set with the given invite code.

Input:

{
  "token": "",
  "code": "",
}

Output:

{
  "success": true,
  "id": "",
}

`v1/leaveSet`: Leave a set

Removes the authenticated user from the given set.

Input:

{
  "token": "",
  "set": "",
}

Output:

{ "success": true }

`v1/updateSet`: Update or delete set

Updates the details of the given set or deletes it. Requires admin privileges over the set.

Input:

{
  "token": "",
  "set": "",
  "name?": "",
  "icon?": "",
  "delete?": false
}

Output:

{ "success": true }

`v1/updateSubset`: Update or delete subset

Updates the details of the given subset or deletes it. Requires admin privileges over the set.

Input:

{
  "token": "",
  "subset": "",
  "name?": "",
  "delete?": false
}

Output:

{ "success": true }

`v1/kick`: Kick a user from a set

Kicks a user from a set. Requires admin privileges over the set.

Input:

{
  "token": "",
  "set": "",
  "uid": ""
}

Output:

{ "success": true }

Messages API

`v1/messages`: Get messages for a subset

Gets messages from the given subset. If set, the before field takes a message ID, and will only return messages sent before that message. If set, the limit field will limit the number of messages returned.

Input:

{
  "token": "",
  "subset": "",
  "before?": "",
  "limit?": ""
}

Output:

{
  "success": true,
  "messages": [
    {
      "id": "",
      "content": "",
      "authorId": "",
      "authorName": "",
      "authorImage?": "",
      "attachment?": {
        "id": "",
        "name": "",
        "type": "",
      },
      "sendTime": "",
    }
  ]
}

`v1/sendMessage`: Send a message to a subset

Sends a message from the given user to the given subset.

Input:

{
  "token": "",
  "subset": "",
  "message": "",
  "attachment?": {
    "name": "",
    "data": "<base64>"
  }
}

Output:

{ "success": true }

`v1/updateMessage`: Update or delete message

Updates the content of the given message or deletes it. Requires the user to be the author of the message.

Input:

{
  "token": "",
  "message": "",
  "content?": "",
  "delete?": false
}

Output:

{ "success": true }

`v1/typing`: Send typing notification

Informs members of the given set that the user has recently typed in the message box.

Input:

{
  "token": "",
  "subset": ""
}

Output:

{ "success": true }

HTTP-Only API

Some routes are only available via HTTP.

Files

Files API

`v1/files/{id}`: Get file

Gets the file with the given ID. This endpoint does not require authentication.

`v1/updateUserImage`: Update user image

Updates the current user's image. This endpoint requires authentication to identify and authenticate the user.

Input:

Binary file
X-File-Name header with the file name
X-Equion-Token header with the user's token

WebSocket-Only API

Some routes are only available via WebSocket. Additionally, these routes often trigger or relate to events, which are sent over WebSocket.

General WebSocket API

Subscribes the WebSocket connection to updates for the given set.

Input:

{
  "token": "",
  "set": ""
}

Output:

{ "success": true }

`v1/unsubscribe`: Unsubscribe from a set

Unsubscribes the WebSocket connection from updates for the given set.

Input:

{
  "token": "",
  "set": ""
}

Output:

{ "success": true }

`v1/ping`: Pings the server

Pings the server to check if the connection is still alive.

Input:

{ }

Output:

(triggers a pong event)

Voice API

`v1/connectUserVoice`: Register user voice connection

Registers a user's voice connection allowing them to use voice chat features.

Input:

{
  "token": "",
  "peerId": ""
}

Output:

{ "success": true }

`v1/disconnectUserVoice`: Unregister user voice connection

Unregisters a user's voice connection.

Input:

{ "token": "" }

Output:

{ "success": true }

`v1/connectToVoiceChannel`: Connect to voice channel

Connects the user to the given voice channel.

Input:

{
  "token": "",
  "channel": "",
}

Output:

{ "success": true }

`v1/leaveVoiceChannel`: Leave current voice channel

Leaves the user's current voice channel.

Input:

{ "token": "" }

Output:

{ "success": true }

Events

These are sent to the client when events happen in a set.

`v1/set`: Set event

Sent when a set is modified, deleted, or the user has been kicked.

{
  "event": "v1/set",
  "set": "",
  "deleted": false,
  "data": {
    "name?": "",
    "icon?": "",
    "kicked?": false
  }
}

`v1/subset`: Subset event

Sent when a subset is created, modified or deleted.

{
  "event": "v1/subset",
  "set": "",
  "subset": {
    "id": "",
    "name": "",
  },
  "deleted": false
}

`v1/message`: Message event

Sent when a message is sent, modified or deleted.

{
  "event": "v1/message",
  "set": "",
  "subset": "",
  "message": {
    "id": "",
    "content": "",
    "authorId": "",
    "authorName": "",
    "authorImage?": "",
    "attachment?": {
      "id": "",
      "name": "",
      "type": "",
    },
    "sendTime": "",
  },
  "deleted": false
}

`v1/user`: User event

Sent when a user joins a set, updates their details, or leaves a set.

{
  "event": "v1/user",
  "set": "",
  "user": {
    "uid": "",
    "username": "",
    "displayName": "",
    "email": "",
    "image?": "",
    "bio?": "",
    "online": true
  },
  "deleted": false
}

`v1/voice`: Voice event

Sent when a user joins or leaves a voice channel.

{
  "event": "v1/voice",
  "set": "",
  "user": {
    "peerId": "",
    "user": {
      "uid": "",
      "username": "",
      "displayName": "",
      "email": "",
      "image?": "",
      "bio?": ""
    }
  },
  "deleted": false
}

`v1/typing`: User recently typed

Sent when a user types in the message box.

{
  "event": "v1/typing",
  "subset": "",
  "uid": ""
}

`v1/pong`: Pong

Sent when a ping is received.

{
  "event": "v1/pong"
}

Message Encoding

Messages are encoded in Equion in a similar way to Discord, but Equion also supports LaTeX expressions. Messages are stored as a string, with the following patterns having special meaning.

Patterns

Name	Regex Pattern (Simplified)	Example	Example Parsed
Block LaTeX (`\[ \]` delimiters)	`/\\\[.*\\\]/`	`\[x^2\]`	$x^2$
Inline LaTeX (`` delimiters)	`/\\$.*\\$/`	`$x^2$`	$x^2$
Block LaTeX (`$$ $$` delimiters)	`/\$\$.*\$\$/`	`$$x^2$$`	$x^2$
Inline LaTeX ( $ $ delimiters)	`/\$.*\$/`	$x^2$	$x^2$
Bold	`/\\.\\*/`	`bold`	bold
Italic	`/\.\*/`	`italic`	italic
Underline	`/__.*__/`	`__underline__`	underline
Strike	`/\~\~.*\~\~/`	`~~strikethrough~~`	~~strikethrough~~
Ping	`/<@[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}>/`	`<@115bf718-d12d-11ec-9d64-0242ac120002>`	@William Henderson
Link	`/https?:\/\/[^\s]+/`	`https://whenderson.dev/blog`	https://whenderson.dev/blog

Note that for pings, the client would type @William Henderson which would be automatically converted to the ID when the message is sent.

Equion Developer Docs