AppView

The Colibri AppView is responsible for aggregating message data from across the network and providing endpoints for interacting with this data. Any requests to the AppView are meant to be proxied via the user’s PDS, to which the client application makes the requests. When requests are forwarded, the following DID URI should be used to indicate the target:

did:web:api.colibri.social#colibri_appview

Implemented Endpoints

The AppView supports a range of XRPC methods that PDSs can call. All com.atproto endpoints adhere to the original specification. There are also certain social.colibri XRPC endpoints which allow for extended functionality. All of these endpoints are available under the /xrpc/ path.

`com.atproto.identity.resolveDid`

Resolves a DID to a DID document. Does not bi-directionally verify the handle.

GET /xrpc/com.atproto.identity.resolveDid

Unauthenticated

Query Parameters

did (did)

Required

Response

didDoc (DID Document)

Required

`com.atproto.identity.resolveHandle`

Resolves an atproto handle (hostname) to a DID. Does not necessarily bi-directionally verify against the the DID document.

GET /xrpc/com.atproto.identity.resolveHandle

Unauthenticated

Query Parameters

handle (handle)

Required

Response

did (did)

Required

`com.atproto.identity.resolveIdentity`

Resolves an atproto handle (hostname) to a DID. Does not necessarily bi-directionally verify against the the DID document.

GET /xrpc/com.atproto.identity.resolveIdentity

Unauthenticated

Query Parameters

identifier (did | handle)

Required

Response

did (did)

Required

handle (handle)

Required

didDoc (DID Document)

Required

`com.atproto.repo.getRecord`

Get a single cached record from the AppView.

GET /xrpc/com.atproto.repo.getRecord

Unauthenticated

Query Parameters

repo (at-identifier)

Required

collection (nsid)

Required

rkey (record-key)

Required

cid (cid)

Response

uri (at-uri)

Required

value (object)

Required

cid (cid)

`com.atproto.repo.listRecords`

List a range of cached records in a repository, matching a specific collection.

GET /xrpc/com.atproto.repo.listRecords

Unauthenticated

Query Parameters

repo (at-identifier)

Required

collection (nsid)

Required

limit (integer)

cursor (string)

reverse (boolean)

Response

cursor (string)

records (object[])

Required

`social.colibri.actor.getData`

Get the status data and bluesky profile for a Colibri user.

GET /xrpc/social.colibri.actor.getData

Unauthenticated

Query Parameters

itendifier (did | handle)

Required

Response

did (did)

Required

handle (handle)

Required

data (object)

Required

displayName (string)

Required

avatar (blob)

banner (blob)

description (string)

onlineState (string)

Required

status (object)

emoji (string)

text (string)

Required

`social.colibri.actor.setState`

Sets the online state for a Colibri user.

POST /xrpc/social.colibri.actor.setState

Requires Authentication

Query Parameters

state (string)

Required

Response

onlineState (string)

Required

`social.colibri.actor.listCommunities`

Lists all communities the Colibri user is a part of (and not blocked from).

GET /xrpc/social.colibri.actor.listCommunities

Requires Authentication

Response

communities (object[])

Required

name (string)

Required

picture (blob)

description (string)

categoryOrder (string[])

uri (at-uri)

requiresApprovalToJoin (boolean)

Required

`social.colibri.sync.subscribeEvents`

Opens a connection with a WebSocket stream that transmits relevant events for the user.

WS /xrpc/social.colibri.sync.subscribeEvents

Requires Authentication

Events

The event stream can choose to transmit events to clients who have signed up to receive them. All events follow the same JSON data structure: they have a type (which is the same as the heading below), and an optional data field.

`ack`

Sent when the AppView receives a heartbeat message from the client. This event carries no data.

`community_event`

Events of this type are sent to clients when a community has been updated or deleted. If the event is set to delete, only the community’s uri needs to be supplied.

{
  event: 'upsert' | 'delete';
  uri: string;
  name: string;
  description: string;
  picture: blob;
  categoryOrder: string[];
}

`member_event`

Events of this type are sent to clients when a member has joined or left (or been blocked from) a community. The membership property is an AT-URI to the user’s membership declaration for the community.

{
  event: 'join' | 'leave';
  community: string;
  membership: string;
}

`category_event`

Events of this type are sent to clients when a category has been created, updated, or deleted. When the event is delete, the name and channelOrder can be omitted.

{
  event: 'upsert' | 'delete';
  uri: string;
  community: string;
  name: string;
  channelOrder: string[];
}

`channel_event`

Events of this type are sent to clients when a channel has been created, updated, or deleted. When the event is delete, the name, description, and type can be omitted.

{
  event: 'upsert' | 'delete'
  uri: string;
  community: string;
  name: string;
  description: string;
  type: string;
}

`message_event`

Events of this type are sent to clients when a message has been sent, edited, or deleted. When the event is delete, anything but the uri and channel can be omitted.

{
  event: 'upsert' | 'delete';
  uri: string;
  channel: string;
  text: string;
  facets: facet[];
  createdAt: string;
  indexedAt: string;
  edited: boolean;
  parent: string;
  attachments: blob[];
}

`reaction_event`

Events of this type are sent to clients when a reaction has been added to or removed from a message.

{
  event: 'added' | 'removed';
  uri: string;
  emoji: string;
  target: string;
  channel: string;
}

`user_event`

Events of this type are sent to clients when a user the client knows about has updated their Bluesky profile or Colibri status.

{
  did: string;
  status?: {
    emoji?: string;
    text: string;
    state: 'online' | 'away' | 'dnd' | 'offline';
  };
  profile: {
    displayName?: string;
    avatar?: blob;
    banner?: blob;
    description?: string;
    handle: string;
  };
}

`typing_event`

Events of this type are sent to clients when a user is typing in the channel the user is currently viewing. For notes on how to report this to the AppView, see the view message type.

{
  event: 'start' | 'stop';
  channel: string;
  did: string;
}

Messages

The following messages can be sent from the client to the AppView. All messages follow the same JSON data structure: they have a type (which is the same as the heading below), and an optional data field.

`heartbeat`

A generic event that carries no data. It is used to keep the socket connection alive. The AppView will always respond with an ack event.

`subscribe`

Clients can send a subscribe message to the AppView, supplying a list of communities for which they wish to receive updates. The AppView handles the rest and infers which users, channels, etc. the client needs to know about.

{
  communities: string[];
}

`view`

Clients can send a view message to the AppView to inform it about the channel the user is currently viewing.

{
  channel: string;
}

`unsubscribe`

Clients can send an unsubscribe message to the AppView, supplying a list of communities, for which they wish to no longer receive events.

{
  communities: string[];
}

`activity`

A message used to prevent clients from having their online status set to “Away” after a certain amount of time. Clients should send this message periodically while the user actively interacts with the app.

`voice_join`

Clients must send a voice_join message to the AppView when the user joins a voice channel.

{
  channel: string;
  community: string;
}

`voice_leave`

Clients must send a voice_leave message to the AppView when the user leaves a voice channel.

{
  channel: string;
  community: string;
}

`social.colibri.community.listBlockedUsers`

Lists all blocked users for a community.

GET /xrpc/social.colibri.community.listBlockedUsers

Unauthenticated

Query Parameters

community (at-uri)

Required

Response

dids (did[])

Required

`social.colibri.community.listCategories`

Lists all categories in a community.

GET /xrpc/social.colibri.community.listCategories

Unauthenticated

Query Parameters

community (at-uri)

Required

Response

categories (object[])

Required

uri (at-uri)

Required

name (string)

Required

channelOrder (at-uri[])

Required

`social.colibri.community.listChannels`

Lists all channels in a community.

GET /xrpc/social.colibri.community.listChannels

Unauthenticated

Query Parameters

community (at-uri)

Required

Response

channels (object[])

Required

uri (at-uri)

Required

name (string)

Required

type (string)

Required

category (at-uri)

Required

`social.colibri.community.listMembers`

Lists all members with their roles, status information and Bluesky profiles.

GET /xrpc/social.colibri.community.listMembers

Unauthenticated

Query Parameters

community (at-uri)

Required

Response

members (object[])

Required

did (did)

Required

handle (handle)

Required

data (object)

Required

displayName (string)

Required

avatar (blob)

banner (blob)

description (string)

onlineState (string)

Required

status (object)

emoji (string)

text (string)

Required

`social.colibri.community.blockMessage`

Block a message in a given community.

POST /xrpc/social.colibri.community.blockMessage

Requires Authentication

Query Parameters

community (at-uri)

Required

message (at-uri)

Required

Response

message (at-uri)

Required

`social.colibri.community.blockUser`

Block a user from writing messages in a given community.

POST /xrpc/social.colibri.community.blockUser

Requires Authentication

Query Parameters

community (at-uri)

Required

identifier (did | handle)

Required

Response

did (did)

Required

handle (handle)

Required

`social.colibri.community.unblockUser`

Unblock a user from a community, allowing them to write messages there again.

POST /xrpc/social.colibri.community.unblockUser

Requires Authentication

Query Parameters

community (at-uri)

Required

identifier (did | handle)

Required

Response

did (did)

Required

handle (handle)

Required

`social.colibri.community.createInvitation`

Create an invitation for the specified community.

POST /xrpc/social.colibri.community.createInvitation

Requires Authentication

Query Parameters

community (at-uri)

Required

Response

code (string)

Required

community (at-uri)

Required

createdBy (did)

Required

active (boolean)

Required

`social.colibri.community.resolveInvitation`

Get information about a given invitation code.

GET /xrpc/social.colibri.community.getInvitation

Requires Authentication

Query Parameters

code (string)

Required

Response

code (string)

Required

community (at-uri)

Required

createdBy (did)

Required

active (boolean)

Required

`social.colibri.community.listInvitations`

List all invitations for the specified community.

POST /xrpc/social.colibri.community.listInvitations

Requires Authentication

Query Parameters

uri (at-uri)

Required

Response

codes (object[])

Required

code (string)

Required

community (at-uri)

Required

createdBy (did)

Required

active (boolean)

Required

`social.colibri.community.deleteInvitation`

Delete an invitation for the specified community.

POST /xrpc/social.colibri.community.deleteInvitation

Requires Authentication

Query Parameters

uri (at-uri)

Required

code (string)

Required

Response

code (string)

Required

`social.colibri.channel.listMessages`

Get a paginated message history for the specified channel, newest messages first.

GET /xrpc/social.colibri.channel.listMessages

Unauthenticated

Query Parameters

channel (at-uri)

Required

limit (integer)

cursor (string)

all (boolean)

Response

messages (object[])

Required

uri (at-uri)

Required

text (string)

Required

facets (Facet[])

Required

channel (at-uri)

Required

community (at-uri)

Required

author (did)

Required

parent (at-uri)

Required

attachments (blob[])

Required

reactions (object[])

Required

emoji (string)

Required

count (integer)

Required

reactorDIDs (string[])

Required

`social.colibri.channel.getReadCursor`

Get the read cursor for the current user and specified channel.

GET /xrpc/social.colibri.channel.getReadCursor

Requires Authentication

Query Parameters

channel (at-uri)

Required

Response

uri (at-uri)

Required

cursor (string)

Required

channel (at-uri)

Required

`social.colibri.message.listReactions`

Get all reactions for a specified message, grouped by emoji with reactor DIDs.

GET /xrpc/social.colibri.channel.listReactions

Unauthenticated

Query Parameters

message (at-uri)

Required

Response

reactions (object[])

Required

emoji (string)

Required

count (integer)

Required

reactorDIDs (string[])

Required

Humming

The Colibri infrastructure is designed to be easy to self-host. In cases where users prefer to host their own infrastructure, under normal circumstances, data that is not saved on the protocol (like online/offline status, writing presence, etc.) is not able to be transmitted to other users who use a different app view.

The Colibri AppView supports a system called Humming to curcumvent this. Other AppView instances that wish to share off-protocol status data with users on other instances can share them via a Hum, a message sent to another AppView instance’s social.colibri.sync.sendHum endpoint, which can then choose to relay it to its clients via its social.colibri.sync.subscribeEvents WebSocket stream. Additionally, AppViews that wish to forward these events to other AppViews can expose a social.colibri.sync.subscribeHums endpoint, to which other AppViews can subscribe.

`social.colibri.sync.sendHum`

Inform another AppView of an event that has occured.

POST /xrpc/social.colibri.sync.sendHum

Unauthenticated

Query Parameters

event (object)

Required

`social.colibri.sync.subscribeHums`

WS /xrpc/social.colibri.sync.subscribeHums

Unauthenticated

For transmitted event types, please refer to social.colibri.sync.subscribeEvents.