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.sync.getRecord`

Get a single cached record from the AppView.

GET /xrpc/com.atproto.sync.getRecord

Unauthenticated

Query Parameters

repo (at-identifier)

Required

collection (nsid)

Required

rkey (record-key)

Required

Response

uri (at-uri)

Required

value (object)

Required

`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)

Required

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, all data except the uri and event 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, all data except the uri and event 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, all data except the uri and event 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. When the event is removed, all data except the uri and event can be omitted.

{
  event: 'added' | 'removed';
  uri: string;
  emoji: string;
  target: 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.

`view`

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

{
  channel: string;
}

`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.

`social.colibri.community.create`

Mints a new community DID on the AppView’s own PDS and bootstraps a fully populated community. The AppView authenticates against PDS_LOC using PDS_ADMIN_USER / PDS_ADMIN_PASS (HTTP Basic) so it can create accounts without an invite code, stores the new account’s credentials encrypted in community_credentials, and writes five records to the new repo:

social.colibri.community (pinned at rkey: "self")
social.colibri.category — a default "General" category
social.colibri.channel — a default "general" text channel inside that category
social.colibri.role — an "Owner" role with every permission and protected: true so role-management endpoints refuse to delete it
social.colibri.member — subject = authenticated caller, holding the Owner role

The caller ends up as an owner-equivalent member of the new community.

POST /xrpc/social.colibri.community.create

Requires Authentication

Query Parameters

name (string)

Required

description (string)

requires_approval_to_join (boolean)

Response

did (did)

Required

community (at-uri)

Required

category (at-uri)

Required

channel (at-uri)

Required

ownerRole (at-uri)

Required

member (at-uri)

Required

The AppView identifies communities by DID; handles minted alongside the account are an implementation detail of PDS hosting and are not expected to be used for identity resolution. The AppView fails to start if any of PDS_LOC, PDS_ADMIN_USER, PDS_ADMIN_PASS, APPVIEW_HANDLE_DOMAIN, or CREDENTIAL_ENCRYPTION_KEY are missing.

`social.colibri.community.registerCredentials`

Registers user-supplied credentials (PDS endpoint + identifier + app password) for an existing community DID hosted on a PDS the AppView doesn’t manage. The AppView verifies proof-of-control by performing a com.atproto.server.createSession against the supplied PDS — if the resulting session’s DID matches the claimed community DID, the credentials are accepted, encrypted with AES-256-GCM, and stored. No bootstrap happens; BYO callers are expected to provision the community records themselves.

POST /xrpc/social.colibri.community.registerCredentials

Requires Authentication

Query Parameters

did (did)

Required

pds (uri)

Required

identifier (at-identifier)

Required

password (string)

Required

Response

did (did)

Required

source (string)

Required

`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.listRoles`

Lists all roles cached for a community.

GET /xrpc/social.colibri.community.listRoles

Unauthenticated

Query Parameters

community (at-uri)

Required

Response

roles (object[])

Required

uri (at-uri)

Required

name (string)

Required

color (string)

permissions (string[])

Required

position (integer)

Required

hoisted (boolean)

mentionable (boolean)

protected (boolean)

channelOverrides (object[])

Required

channel (at-uri)

Required

allow (string[])

Required

deny (string[])

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

roles (at-uri[])

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.getData`

Returns all cached data for a community in a single response: the community record, its categories, channels, roles, and members. Returns NotFound if no community record is cached for the given URI.

GET /xrpc/social.colibri.community.getData

Unauthenticated

Query Parameters

community (at-uri)

Required

Response

community (object)

Required

uri (at-uri)

Required

name (string)

Required

description (string)

Required

picture (blob)

categoryOrder (at-uri[])

Required

requiresApprovalToJoin (boolean)

Required

categories (object[])

Required

uri (at-uri)

Required

name (string)

Required

channelOrder (at-uri[])

Required

channels (object[])

Required

uri (at-uri)

Required

name (string)

Required

type (string)

Required

category (at-uri)

Required

roles (object[])

Required

uri (at-uri)

Required

name (string)

Required

color (string)

permissions (string[])

Required

position (integer)

Required

hoisted (boolean)

mentionable (boolean)

protected (boolean)

channelOverrides (object[])

Required

channel (at-uri)

Required

allow (string[])

Required

deny (string[])

Required

members (object[])

Required

did (did)

Required

handle (handle)

Required

roles (at-uri[])

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.resolveInvitation

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.message.listReactions

Unauthenticated

Query Parameters

message (at-uri)

Required

Response

reactions (object[])

Required

emoji (string)

Required

count (integer)

Required

reactorDIDs (string[])

Required

`social.colibri.notification.listNotifications`

Returns a paginated list of notifications for the authenticated user, newest first. Each notification embeds the underlying message body so clients can render the notification without a follow-up fetch. message is omitted if the underlying message has been removed from the AppView cache.

GET /xrpc/social.colibri.notification.listNotifications

Requires Authentication

Query Parameters

limit (integer)

cursor (string)

Response

cursor (string)

notifications (object[])

Required

id (integer)

Required

recipientDid (did)

Required

kind (string)

Required

messageUri (at-uri)

Required

authorDid (did)

Required

channelRkey (record-key)

Required

indexedAt (datetime)

Required

seenAt (datetime)

message (object)

text (string)

Required

facets (Facet[])

Required

createdAt (datetime)

Required

parent (record-key)

attachments (blob[])

Required

edited (boolean)

The kind value is one of:

mention — the authenticated user appears as a social.colibri.richtext.facet#mention feature in the message’s facets.
reply — the message’s parent resolves to a message authored by the authenticated user.

Mentions and replies are deduplicated per (recipient, message, kind), so a single message that both mentions and replies to the recipient produces two notification rows.

`social.colibri.notification.getUnreadCount`

Returns the count of unseen notifications for the authenticated user.

GET /xrpc/social.colibri.notification.getUnreadCount

Requires Authentication

Response

count (integer)

Required

`social.colibri.notification.updateSeen`

Marks every unseen notification for the authenticated user whose indexedAt is at or before seenAt as seen. If seenAt is omitted, the AppView uses its current clock for both the cutoff and the stamped seenAt — equivalent to “mark everything currently indexed as seen now”.

POST /xrpc/social.colibri.notification.updateSeen

Requires Authentication

Query Parameters

seenAt (datetime)

Response

updated (integer)

Required

`notification_event`

Notification events are emitted over social.colibri.sync.subscribeEvents immediately after a notification is indexed. The payload mirrors a single entry of listNotifications and always carries the message body — clients should not need to perform a follow-up fetch.

{
  id: integer;
  kind: 'mention' | 'reply';
  messageUri: string;
  authorDid: string;
  channelRkey: string;
  indexedAt: string;
  message: {
    text: string;
    facets: facet[];
    createdAt: string;
    parent?: string;
    attachments: blob[];
    edited?: boolean;
  };
}

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.