Help > Getting Started with Trillian Server's RESTful API

Getting Started Schema Parameters Client Errors HTTP Verbs Authentication Group Chats Media Members Messages Groups Peers Policies Presence Users Address Book Media Messages Security

Getting Started

This guide is intended to get you up-and-running with Trillian Server's RESTful API. It covers the basic concepts of how the API works and goes into examples for each possible API endpoint. We've followed an API "dogfooding" approach here at Cerulean Studios which means that all of our own management software relies on our API to operate, so you should be be able to mirror virtually everything our own tools are capable of by leveraging this API.

The Trillian Server API is only available to Trillian for Business customers.

Schema

All API access is over HTTPS, and accessed from https://api.trillian.im or the fully-qualified domain name you've configured for your in-house Trillian Server. All data returned by the API is sent as XML.

Parameters

For GET requests, parameters not specified in the URL can be passed to the API in the HTTP query string, e.g.:

$ curl "https://api.trillian.im/v2/ceruleanstudios.com/groupchats/?members=1"

For POST, PATCH, and DELETE requests, parameters not included in the URL should be sent in the request body using the MIME type of application/x-www-form-urlencoded, e.g.:

$ curl https://api.trillian.im/v2/ceruleanstudios.com/users/ \
   -d im=smw@ceruleanstudios.com \
   -d password=xhTTrDc%23p%5C8P9%3D4B \
   -d email=smw@ceruleanstudios.com

Client Errors

There are a few possible types of client errors:

  1. Sending a request with invalid or missing parameters will result in a 400 Bad Request.
  2. Sending a request without a valid API token will result in a 401 Not Authorized.
  3. Sending a request to an empty endpoint will result in a 404 Not Found.
  4. A request that otherwise cannot be fulfilled will result in a 500 Internal Server Error.

HTTP Verbs
Verb Description
HEAD Can be issued against media resources to get information about the media prior to retrieving it in full.
GET Used for retrieving resources.
POST Used for creating resources.
PATCH Used for partially updating resources. For example, a PATCH request can be used to update a user's email address without having to provide the rest of the attributes for the user when doing so. All endpoints also accept POST requests in the event that PATCH is unavailable in a particular environment.
DELETE Used for deleting resources.

Authentication

All requests to the Trillian Server API must be authenticated by appending a token parameter to the URL of the request. For example:

$ curl "https://api.trillian.im/v2/ceruleanstudios.com/groupchats/?token=AVS%2Fw8J7UELk4Q9pB5iz66p9J8WTbNZprvYO%2F7wOUekj9JfiMjs3A46qoefKRGMGeqUmWYVapz7UBpKXNbW3P62C4vhzy%2B3XEVcvXxh8ebKf9RXJDhXMeWzJwcwh4zuI6PgWnBKZRYiTWk6c%2B98cWdY8bjTm8j%2FG4wI9%2Foex%2FVVh"

Group Chats

Group chats are named, persistent, many-to-many conversations between your users. Use the group chats API to create or manipulate group chats, add and remove members to and from existing group chats, get group chat message history, and send instant messages to group chats.

Get all group chats

GET /v2/:domain/groupchats/

Parameters

Name Type Description
groups integer An integer set to 1 if groups should be expanded in the response. Optional, default is 0.
members integer An integer set to 1 if members should be expanded in the response. Optional, default is 0.

Response

HTTP/1.1 200 OK
<response> <groupchat name="#e777b98d42ae25754f3ae6bd2847dc8967ae8c5c@ceruleanstudios.com"> <displayname>General</displayname><flags>7936</flags><groups href="https://api.trillian.im/v2/.../groups/"/><media href="https://api.trillian.im/v2/.../media/"/><members href="https://api.trillian.im/v2/.../members/"/><messageTimestamp>0</messageTimestamp><messages href="https://api.trillian.im/v2/.../messages/"/><topic>Welcome to Cerulean HQ!</topic></groupchat><groupchat name="#68f04b7ecef949cbf7d775f3c18c4e2c50b98969@ceruleanstudios.com"> <displayname>Development</displayname><flags>256</flags><groups href="https://api.trillian.im/v2/.../groups/"/><media href="https://api.trillian.im/v2/.../media/"/><members href="https://api.trillian.im/v2/.../members/"/><messageTimestamp>0</messageTimestamp><messages href="https://api.trillian.im/v2/.../messages/"/><topic>Developers, developers, developers, developers!</topic></groupchat></response>

Get a single group chat

GET /v2/:domain/groupchats/:groupchat/

Parameters

Name Type Description
groups integer An integer set to 1 if groups should be expanded in the response. Optional, default is 0.
members integer An integer set to 1 if members should be expanded in the response. Optional, default is 0.

Response

HTTP/1.1 200 OK
<response> <groupchat name="#e777b98d42ae25754f3ae6bd2847dc8967ae8c5c@ceruleanstudios.com"> <displayname>General</displayname><flags>7936</flags><groups href="https://api.trillian.im/v2/.../groups/"/><media href="https://api.trillian.im/v2/.../media/"/><members href="https://api.trillian.im/v2/.../members/"/><messageTimestamp>0</messageTimestamp><messages href="https://api.trillian.im/v2/.../messages/"/><topic>Welcome to Cerulean HQ!</topic></groupchat></response>

Create a group chat

POST /v2/:domain/groupchats/

Parameters

Name Type Description
displayname string A displayname for the new group chat.
flags integer Flags for the new group chat.

Group chat flags are represented by an unsigned 32-bit integer. Combine one or more flags to calculate the final result from the following options:

#define GROUPCHAT_DELETED0x00000001
#define GROUPCHAT_DISABLE_DISPLAYNAME_SET0x00000100
#define GROUPCHAT_DISABLE_TOPIC_SET0x00000200
#define GROUPCHAT_DISABLE_LIST0x00000400
#define GROUPCHAT_DISABLE_MEMBER_ADD0x00000800
#define GROUPCHAT_DISABLE_MEMBER_REMOVE0x00001000
#define GROUPCHAT_DISABLE_MESSAGE_SEND0x00002000
When utilizing flags to restrict user permissions for a group chat, remember that all users marked as operators can change these flags and themselves are not bound by them.

Response

HTTP/1.1 201 Created
<response> <groupchat name="#bf1fe6f61bd917cc5dae911945b6dec415dbe9aa@ceruleanstudios.com"> <displayname>Sales</displayname><flags>0</flags><groups href="https://api.trillian.im/v2/.../groups/"/><media href="https://api.trillian.im/v2/.../media/"/><members href="https://api.trillian.im/v2/.../members/"/><messageTimestamp>0</messageTimestamp><messages href="https://api.trillian.im/v2/.../messages/"/><topic/></groupchat></response>

Update a group chat

PATCH /v2/:domain/groupchats/:groupchat/

Parameters

Name Type Description
displayname string A displayname for the group chat. Unless a user has renamed a group chat and overridden the server-provided displayname, all users will see the new displayname appear in their contact list and message window.
flags integer Flags for this group chat.
topic string A topic for the group chat, displayed at the top of the message window.

Response

HTTP/1.1 200 OK
<response> <groupchat name="#e777b98d42ae25754f3ae6bd2847dc8967ae8c5c@ceruleanstudios.com"> <displayname>General</displayname><flags>7936</flags><groups href="https://api.trillian.im/v2/.../groups/"/><media href="https://api.trillian.im/v2/.../media/"/><members href="https://api.trillian.im/v2/.../members/"/><messageTimestamp>0</messageTimestamp><messages href="https://api.trillian.im/v2/.../messages/"/><topic>This is a brand new topic!</topic></groupchat></response>

Group Chat Media

Get all media owned by a group chat

GET /v2/:domain/groupchats/:groupchat/media/

Response

HTTP/1.1 200 OK
<response> <media m="oaoE1007PaKuresDf88IEcxJ6xsFWS/SuLWP/kzzIjs="> <createdAt>1464196567</createdAt><expiresAt>0</expiresAt><size>6</size><owner>#5b8fa79923cddcc8be3060bad620442f40749db6@ceruleanstudios.com</owner><type>text/plain</type><name>Sales Goals.txt</name><thumbnail>CdKtFMRivzsnZ0N8r6L/rnLUsfvMh4D6By9zvbNZMJQ=</thumbnail><data>15CtxdA8qY5XzScZvkOFxgP3nwm8W6cd9sohnOiIw/w=</data></media><media m="ZZQbFbiyRJ1IJdlIkaQkIwXkDFa2K8NKmC+3pwjR7wU="> <createdAt>1464196628</createdAt><expiresAt>0</expiresAt><size>77998</size><owner>#5b8fa79923cddcc8be3060bad620442f40749db6@ceruleanstudios.com</owner><type>image/jpeg</type><name>Stage 3 Mockup.jpg</name><thumbnail>+O4CeLzBE7pYX0YVvhn449D3A2T7HS+E9lnuyR1D2vE=</thumbnail><data>2/DYBl/eBNjfv7oRayHjIljey2c+zZWv19AqZ8SvDRE=</data></media></response>

Get a single media item owned by a group chat

GET /v2/:domain/groupchats/:groupchat/media/:item/

Response

HTTP/1.1 200 OK

Create a media item owned by a group chat

POST /v2/:domain/groupchats/:groupchat/media/

Parameters

Name Type Description
data string A Base64 encoded string of the media data.
imageheight integer An integer representing the height of the image being uploaded, if applicable. Optional.
imagewidth integer An integer representing the width of the image being uploaded, if applicable. Optional.
name string The filename of the media item being uploaded.
thumbnail string A Base64 encoded string of the thumbnail data that should be associated with the new media item. Thumbnails cannot exceed 65535 bytes.
type string The MIME type of the media item being uploaded, e.g. image/png.

Response

HTTP/1.1 201 Created

Delete a media item owned by a group chat

DELETE /v2/:domain/groupchats/:groupchat/media/:item/

Response

HTTP/1.1 204 No Content

Group Chat Members

Get all members of a group chat

GET /v2/:domain/groupchats/:groupchat/members/

Response

HTTP/1.1 200 OK
<response> <members href="https://api.trillian.im/v2/.../members/"> <member name="smw@ceruleanstudios.com"> <flags>1</flags></member><member name="kwk@ceruleanstudios.com"> <flags>3</flags></member></members></response>

Group chat member flags are represented by an unsigned 32-bit integer. Combine one or more flags to calculate the final result from the following options:

#define GROUPCHAT_MEMBER_OP0x00000001
#define GROUPCHAT_MEMBER_VOICE0x00000002
Remember that a user can be both an operator and have a voice in a moderated group chat.

Add a member to a group chat

POST /v2/:domain/groupchats/:groupchat/members/:member/

Response

HTTP/1.1 201 Created
<response> <member name="kwk@ceruleanstudios.com"> <flags>0</flags></member></response>

Delete a member from a group chat

DELETE /v2/:domain/groupchats/:groupchat/members/:member/

Response

HTTP/1.1 204 No Content

Group Chat Messages

Group chat message history is stored internally as a single conversation object broken down by weeks. In order to browse message history for a group chat, first pull all of the weeks and then narrow down the scope to pull per-week message blocks as necessary.

Get all message weeks from a group chat

GET /v2/:domain/groupchats/:groupchat/messages/

Response

HTTP/1.1 200 OK
<response> <messages conversation="c798b870f797b37878fe19cf05198f50d88273dd" medium="astra" name="#5b8fa79923cddcc8be3060bad620442f40749db6@ceruleanstudios.com" revision="3"> <week flags="2" href="https://api.trillian.im/v2/.../messages/c798b870f797b37878fe19cf05198f50d88273dd/2016/20/" messages="3" week="20" year="2016"/></messages></response>

Get messages from a group chat by week

GET /v2/:domain/groupchats/:groupchat/messages/:conversation/:year/:week/

Response

HTTP/1.1 200 OK
<response> <messages> <message timestamp="1464200972389" from="smw@ceruleanstudios.com">This is a test of our new group chat.</message><message timestamp="1464200982855" from="kwk@ceruleanstudios.com">Looks like it's working.</message><message timestamp="1464200982855" from="smw@ceruleanstudios.com">Great - have a lovely day!</message></messages></response>

Send a message to a group chat

POST /v2/:domain/groupchats/:groupchat/messages/

Parameters

Name Type Description
from string The message sender.
message string The message to send.

Response

HTTP/1.1 200 OK
<response> <message timestamp="1464201252102" from="smw@ceruleanstudios.com">Hello from the API!</message></response>
The token provided to this call must be owned by the sender of the message, not the group chat itself.

Delete one or more messages from a group chat

DELETE /v2/:domain/groupchats/:groupchat/messages/:conversation/:year/:week/

Parameters

Name Type Description
block string A Base64 encoded string representing the message block to delete.

Response

HTTP/1.1 204 No Content

Delete messages from a group chat by week

DELETE /v2/:domain/groupchats/:groupchat/messages/:conversation/:year/:week/

Response

HTTP/1.1 204 No Content

Delete all messages from a group chat

DELETE /v2/:domain/groupchats/:groupchat/messages/:conversation/

Response

HTTP/1.1 204 No Content

Groups

Groups are the organization units that make up your business and are visible on user contact lists. In addition to being used for aesthetics, you can use the peer feature of groups to build automatically populated contact lists based on group membership.

Get all groups

GET /v2/:domain/groups/

Parameters

Name Type Description
peers integer An integer set to 1 if peers should be expanded in the response. Optional, default is 0.

Response

HTTP/1.1 200 OK
<response> <group id="1"> <displayname>ceruleanstudios.com</displayname><name>ceruleanstudios.com</name><parent>0</parent><peers href="https://api.trillian.im/v2/ceruleanstudios.com/groups/1/peers/"/><policy>1</policy><priority>0</priority><type>0</type></group><group id="2"> <displayname>Sales</displayname><name>66e71868b7810c7937ec862373a764e6ed36bcaf</name><parent>0</parent><peers href="https://api.trillian.im/v2/ceruleanstudios.com/groups/2/peers/"/><policy>1</policy><priority>0</priority><type>0</type></group><group id="3"> <displayname>Marketing</displayname><name>0c1f49b8d8125e8218c00fd37600d34b80d37f0b</name><parent>0</parent><peers href="https://api.trillian.im/v2/ceruleanstudios.com/groups/3/peers/"/><policy>1</policy><priority>0</priority><type>0</type></group></response>

Get a single group

GET /v2/:domain/groups/:group/

Parameters

Name Type Description
peers integer An integer set to 1 if peers should be expanded in the response. Optional, default is 0.

Response

HTTP/1.1 200 OK
<response> <group id="1"> <displayname>ceruleanstudios.com</displayname><name>ceruleanstudios.com</name><parent>0</parent><peers href="https://api.trillian.im/v2/ceruleanstudios.com/groups/1/peers/"/><policy>1</policy><priority>0</priority><type>0</type></group></response>

Create a group

POST /v2/:domain/groups/

Parameters

Name Type Description
displayname string A displayname for the new group which will be seen by clients.
name string An internal name for the group which must be unique to avoid client issues. Group names are not visible to clients.
parent integer An integer set to the group ID of another group if this group is to be its child, or 0 if not.
policy integer An integer set to the policy ID that should be bound to this group. All users of this group will inherit this policy.
priority integer An integer representing the priority for this group. Used by Trillian Server Manager when resolving conflicts when a user belongs to more than one group on the LDAP side, and not currently used in the cloud environment.
type integer An integer set to 1 if this group is bound to an LDAP object.

Response

HTTP/1.1 200 OK
<response> <group id="4"> <displayname>Development</displayname><name>f7ff9e8b7bb2e09b70935a5d785e0cc5d9d0abf0</name><parent>0</parent><peers href="https://api.trillian.im/v2/ceruleanstudios.com/groups/4/peers/"> <peer id="1"/><peer id="2"/><peer id="3"/><peer id="4"/></peers><policy>1</policy><priority>0</priority><type>0</type></group></response>

Update a group

POST /v2/:domain/groups/:group/

Parameters

Name Type Description
displayname string A displayname for the new group which will be seen by clients.
name string An internal name for the group which must be unique to avoid client issues. Group names are not visible to clients.
parent integer An integer set to the group ID of another group if this group is to be its child, or 0 if not.
policy integer An integer set to the policy ID that should be bound to this group. All users of this group will inherit this policy.
priority integer An integer representing the priority for this group. Used by Trillian Server Manager when resolving conflicts when a user belongs to more than one group on the LDAP side, and not currently used in the cloud environment.
type integer An integer set to 1 if this group is bound to an LDAP object.

Response

HTTP/1.1 200 OK
<response> <group id="3"> <displayname>Marketing</displayname><name>0c1f49b8d8125e8218c00fd37600d34b80d37f0b</name><parent>0</parent><peers href="https://api.trillian.im/v2/ceruleanstudios.com/groups/3/peers/"/><policy>2</policy><priority>0</priority><type>0</type></group></response>

Delete a group

DELETE /v2/:domain/groups/:group/

Response

HTTP/1.1 204 No Content

Group Peers

Use the group peers API to control which groups are peered with which other groups. When users sign in to Trillian, their contact lists will be automatically populated with any users that are peered to the group they belong to.

Get all peers of a group

GET /v2/:domain/groups/:group/peers/

Response

HTTP/1.1 200 OK
<response> <peers href="https://api.trillian.im/v2/ceruleanstudios.com/groups/4/peers/"> <peer id="1"/><peer id="2"/><peer id="3"/><peer id="4"/></peers></response>

Add a peer to a group

POST /v2/:domain/groups/:group/peers/:peer/

Response

HTTP/1.1 201 Created
<response> <peer id="4"/></response>

Remove a peer from a group

DELETE /v2/:domain/groups/:group/peers/:peer/

Response

HTTP/1.1 204 No Content

Policies

Policies are the rules that define what Trillian clients can and cannot do.

Get all policies

GET /v2/:domain/policies/

Response

HTTP/1.1 200 OK
<response> <policy id="1"> <data>dHJpbGxpYW4uZmlsZXRyYW5zZmVyIHNlcnZlcgp0cmlsbGlhbi5oaXN0b3J5LmNsb3VkIDEKdHJpbGxpYW4uaGlzdG9yeS5kaXNjbGFpbWVyLmZyZXF1ZW5jeSAxNDQwCnRyaWxsaWFuLnBsdWdpbi5mYWNlYm9vayAwCnRyaWxsaWFuLnBsdWdpbi5mb3Vyc3F1YXJlIDAKdHJpbGxpYW4ucGx1Z2luLmlyYyAwCnRyaWxsaWFuLnBsdWdpbi5saW5rZWRpbiAwCnRyaWxsaWFuLnBsdWdpbi5tc24gMAp0cmlsbGlhbi5wbHVnaW4ubXlzcGFjZSAwCnRyaWxsaWFuLnBsdWdpbi5vc2NhciAwCnRyaWxsaWFuLnBsdWdpbi5yZW5kZXp2b3VzIDAKdHJpbGxpYW4ucGx1Z2luLnNreXBlIDAKdHJpbGxpYW4ucGx1Z2luLnR3aXR0ZXIgMAp0cmlsbGlhbi5wbHVnaW4ueG1wcCAwCnRyaWxsaWFuLnBsdWdpbi55YWhvbyAwCg==</data><name>ceruleanstudios.com</name></policy><policy id="2"> <data>dHJpbGxpYW4uaGlzdG9yeS5jbG91ZCAxCnRyaWxsaWFuLmhpc3RvcnkuZGlzY2xhaW1lci5mcmVxdWVuY3kgMTQ0MAp0cmlsbGlhbi5zZXR0aW5ncy5jb250YWN0cy5ncm91cHMgc2VydmVyCg==</data><name>IT</name></policy></response>

Get a single policy

GET /v2/:domain/policies/:policy/

Response

HTTP/1.1 200 OK
<response> <policy id="1"> <data>dHJpbGxpYW4uZmlsZXRyYW5zZmVyIHNlcnZlcgp0cmlsbGlhbi5oaXN0b3J5LmNsb3VkIDEKdHJpbGxpYW4uaGlzdG9yeS5kaXNjbGFpbWVyLmZyZXF1ZW5jeSAxNDQwCnRyaWxsaWFuLnBsdWdpbi5mYWNlYm9vayAwCnRyaWxsaWFuLnBsdWdpbi5mb3Vyc3F1YXJlIDAKdHJpbGxpYW4ucGx1Z2luLmlyYyAwCnRyaWxsaWFuLnBsdWdpbi5saW5rZWRpbiAwCnRyaWxsaWFuLnBsdWdpbi5tc24gMAp0cmlsbGlhbi5wbHVnaW4ubXlzcGFjZSAwCnRyaWxsaWFuLnBsdWdpbi5vc2NhciAwCnRyaWxsaWFuLnBsdWdpbi5yZW5kZXp2b3VzIDAKdHJpbGxpYW4ucGx1Z2luLnNreXBlIDAKdHJpbGxpYW4ucGx1Z2luLnR3aXR0ZXIgMAp0cmlsbGlhbi5wbHVnaW4ueG1wcCAwCnRyaWxsaWFuLnBsdWdpbi55YWhvbyAwCg==</data><name>ceruleanstudios.com</name></policy></response>

Create a policy

POST /v2/:domain/policies/

Parameters

Name Type Description
data string A Base64 encoded string representing the policy items that should be enforced.
name string The name of the new policy.

Response

HTTP/1.1 201 Created
<response> <policy id="3"> <data> dHJpbGxpYW4uZmlsZXRyYW5zZmVyIHNlcnZlcgp0cmlsbGlhbi5oaXN0b3J5LmNsb3VkIDEKdHJpbGxpYW4uaGlzdG9yeS5kaXNjbGFpbWVyLmZyZXF1ZW5jeSAxNDQwCnRyaWxsaWFuLnBsdWdpbi5mYWNlYm9vayAwCnRyaWxsaWFuLnBsdWdpbi5mb3Vyc3F1YXJlIDAKdHJpbGxpYW4ucGx1Z2luLmlyYyAwCnRyaWxsaWFuLnBsdWdpbi5saW5rZWRpbiAwCnRyaWxsaWFuLnBsdWdpbi5tc24gMAp0cmlsbGlhbi5wbHVnaW4ubXlzcGFjZSAwCnRyaWxsaWFuLnBsdWdpbi5vc2NhciAwCnRyaWxsaWFuLnBsdWdpbi5yZW5kZXp2b3VzIDAKdHJpbGxpYW4ucGx1Z2luLnNreXBlIDAKdHJpbGxpYW4ucGx1Z2luLnR3aXR0ZXIgMAp0cmlsbGlhbi5wbHVnaW4ueG1wcCAwCnRyaWxsaWFuLnBsdWdpbi55YWhvbyAwCg== </data><name>Marketing</name></policy></response>

Update a policy

PATCH /v2/:domain/policies/:policy/

Parameters

Name Type Description
data string A Base64 encoded string representing the policy items that should be enforced.
name string The name of the new policy.

Response

HTTP/1.1 200 OK
<response> <policy id="3"> <data> dHJpbGxpYW4uZmlsZXRyYW5zZmVyIHNlcnZlcgp0cmlsbGlhbi5oaXN0b3J5LmNsb3VkIDEKdHJpbGxpYW4uaGlzdG9yeS5kaXNjbGFpbWVyLmZyZXF1ZW5jeSAxNDQwCnRyaWxsaWFuLnBsdWdpbi5mYWNlYm9vayAwCnRyaWxsaWFuLnBsdWdpbi5mb3Vyc3F1YXJlIDAKdHJpbGxpYW4ucGx1Z2luLmlyYyAwCnRyaWxsaWFuLnBsdWdpbi5saW5rZWRpbiAwCnRyaWxsaWFuLnBsdWdpbi5tc24gMAp0cmlsbGlhbi5wbHVnaW4ubXlzcGFjZSAwCnRyaWxsaWFuLnBsdWdpbi5vc2NhciAwCnRyaWxsaWFuLnBsdWdpbi5yZW5kZXp2b3VzIDAKdHJpbGxpYW4ucGx1Z2luLnNreXBlIDAKdHJpbGxpYW4ucGx1Z2luLnR3aXR0ZXIgMAp0cmlsbGlhbi5wbHVnaW4ueG1wcCAwCnRyaWxsaWFuLnBsdWdpbi55YWhvbyAwCg== </data><name>Marketing and HR</name></policy></response>

Delete a policy

DELETE /v2/:domain/policies/:policy/

Response

HTTP/1.1 204 No Content

Presence

The presence API lets you retrieve the presence of your users and set presence for individual users.

Get all presence

GET /v2/:domain/presence/

Response

HTTP/1.1 200 OK
<response> <presence name="smw@ceruleanstudios.com" status="2" message="Away since 10:49 AM EDT" timestamp="1464274162"> <devices> <device ip="2315364544" name="BONECRUSHER.D899F043" platform="Windows" version="6.0" build="50"/></devices></presence></response>

Update a user's presence

PATCH /v2/:domain/presence/:imaddress/

Parameters

Name Type Description
message string The status message for this user.
status integer The status for this user.

Response

HTTP/1.1 204 No Content

Users

Get all users

GET /v2/:domain/users/

Response

HTTP/1.1 200 OK

Get a single user

GET /v2/:domain/users/:user/

Response

HTTP/1.1 200 OK

Create a user

POST /v2/:domain/users/

Response

HTTP/1.1 201 Created

Update a user

PATCH /v2/:domain/users/:user/

Response

HTTP/1.1 200 OK

Delete a user

DELETE /v2/:domain/users/:user/

Response

HTTP/1.1 200 OK

User Address Book

Get a user's avatar

GET /v2/:domain/users/:user/addressbook/avatar/

Response

HTTP/1.1 200 OK

Set a user's avatar

PUT /v2/:domain/users/:user/addressbook/avatar/

Response

HTTP/1.1 201 Created

Delete a user's avatar

DELETE /v2/:domain/users/:user/addressbook/avatar/

Response

HTTP/1.1 204 No Content

User Media

Get all media owned by a user

GET /v2/:domain/users/:user/media/

Response

HTTP/1.1 200 OK

Get a single media item owned by a user

GET /v2/:domain/users/:user/media/:item/

Response

HTTP/1.1 200 OK

Create a media item owned by a user

POST /v2/:domain/users/:user/media/

Parameters

Name Type Description
data string A Base64 encoded string of the media data.
imageheight integer An integer representing the height of the image being uploaded, if applicable. Optional.
imagewidth integer An integer representing the width of the image being uploaded, if applicable. Optional.
name string The filename of the media item being uploaded.
thumbnail string A Base64 encoded string of the thumbnail data that should be associated with the new media item.
type string The MIME type of the media item being uploaded, e.g. image/png.

Response

HTTP/1.1 201 Created

Delete a media item owned by a user

DELETE /v2/:domain/users/:user/media/:item/

Response

HTTP/1.1 204 No Content

User Messages

Get all message weeks from a user

GET /v2/:domain/users/:user/messages/

Response

HTTP/1.1 200 OK

Get messages from a user by week

GET /v2/:domain/users/:user/messages/:conversation/:year/:week/

Response

HTTP/1.1 200 OK

Send a message to a user

POST /v2/:domain/users/:user/messages/

Parameters

Name Type Description
from string The message sender.
message string The message to send.

Response

HTTP/1.1 200 OK

Delete one or more messages from a user

DELETE /v2/:domain/users/:user/messages/:conversation/:year/:week/

Parameters

Name Type Description
block string A Base64 encoded string representing the message block to delete.

Response

HTTP/1.1 204 No Content

Delete messages from a user by week

DELETE /v2/:domain/users/:user/messages/:conversation/:year/:week/

Response

HTTP/1.1 204 No Content

Delete all messages from a user

DELETE /v2/:domain/users/:user/messages/:conversation/

Response

HTTP/1.1 204 No Content
© 2025 Cerulean Studios
Contact Us     Legal     Privacy