Lexicons
Colibri defines a set of AT Protocol lexicons for its data types and AppView endpoints. They are grouped below by kind.
Records
Section titled “Records”Persisted records that live in a user’s or community’s repository.
social.colibri.actor.data
The main actor data used in Colibri
The type of the record.
The status for the user, displayed on their profile.
The emoji displayed next to status.
The DIDs of the communities this user is a member of, in the user's preferred sidebar order. Read back by `social.colibri.actor.listCommunities` to restore ordering.
social.colibri.actor.profile
A Colibri-specific user profile. Singleton record on the user's own repo, kept separate from app.bsky.actor.profile so Colibri never needs write access to the Bluesky record.
The type of the record.
The user's display name.
The user's profile description / bio.
The user's avatar image.
The user's profile banner image.
When true, the AppView serves displayName/avatar/banner/description from the user's app.bsky.actor.profile record (Bluesky stays the live source); these mirrored fields may be omitted here.
Colibri-only profile theming. Always sourced from this record regardless of syncBluesky.
DID of the AppView authorized to emit off-protocol presence (status, typing, voice) for this user via Humming. A receiving AppView MUST drop any Hum about this user whose authenticated origin does not equal this value. Absent means the user has not opted into cross-instance presence.
Two-color gradient profile theme.
Primary gradient color as #rrggbb.
Secondary gradient color as #rrggbb.
social.colibri.community
A community, or "server", is where users join to interact with each other on Colibri. Singleton record on the community DID's repo.
The type of the record.
The name of the community.
A description of the community.
An image for the community that will be shown to users.
The order of the categories in this community.
Whether users can chat in this community without the owner having to create an acknowledgement record.
Set on a legacy community record once it has been migrated. Points at the new community record that replaces it; consumers treat this community as retired and hide it.
Set on a community created by migrating a legacy community. Points at the legacy community record this one replaces.
DID of the AppView that administers this community and acts as its off-protocol hub (Humming presence relay and voice SFU host). Written by the credential-holding AppView. Consumers that find this field absent fall back to did:web:api.colibri.social.
social.colibri.category
A category belongs to a community and contains multiple channels on Colibri.
The type of the record.
The name of the category.
The order of the channels in this category.
The community this category belongs to.
social.colibri.channel
A channel that belongs to a category on Colibri.
The type of the record.
The name of the channel.
A description of the channel.
The type of the channel. Colibri provides social.colibri.channel.text, social.colibri.channel.forum, social.colibri.channel.link, and social.colibri.channel.voice.
The category this channel belongs to.
The record key of the community this channel belongs to.
Whether the owner of the community is the only one allowed to post in the channel or not.
Role record-keys allowed to post in this channel. Empty/absent means no role restriction.
Member DIDs explicitly allowed to post in this channel, in addition to allowedRoles.
Set on a channel created by migrating a legacy community. Points at the legacy channel record this one replaces, so message history for the old channel can be surfaced here.
social.colibri.channel.read
A read cursor for a Colibri channel, indicating the last read message by a user.
The type of the record.
The channel this message was sent in.
The timestamp the channel was last read at.
social.colibri.message
A message sent in a channel on Colibri
The type of the record.
The message content.
Annotations of sections of the text.
When the message was sent.
The channel this message was sent in.
Whether this message has been edited.
The record key of a message this message is replying to.
An array of attachment objects for this message.
A file attached to a message.
The attached file.
The original filename.
social.colibri.reaction
A reaction on a Colibri message.
The type of the record.
The emoji of the reaction. This allows for any string to support for custom emojis later down the line.
The message this relation belongs to.
social.colibri.membership
AT-URI of the social.colibri.community record being joined
social.colibri.approval
AT-URI of the user's social.colibri.membership record
AT-URI of the social.colibri.community record
social.colibri.role
A named bundle of permissions assignable to community members. Lives on the community repo.
The type of the record.
Display name of the role.
Optional hex color displayed alongside the role (e.g. '#ff8800').
Permission identifiers granted by this role.
Hierarchy position. Higher values sit higher in the role hierarchy and outrank lower values.
Whether members of this role are displayed separately in the member list.
Whether `@role`-style mentions resolve to this role.
Whether this role is protected from modification or deletion. Set true for system-managed roles (e.g. the bootstrap 'Owner' role minted by `community.create`).
Per-channel permission overrides for this role.
Allow / deny lists scoped to a single channel.
The channel this override applies to.
Permissions granted within this channel.
Permissions denied within this channel. Deny wins over base permissions and overrides allow.
social.colibri.member
A community-side member record granting a user roles within the community. Lives on the community repo and is written when an admission is finalized.
The type of the record.
DID of the admitted user.
Role record-keys assigned to this member on the same community repo.
Optional per-community display-name override for this member.
Optional AT-URI of the user's `social.colibri.membership` declaration this admission was based on.
social.colibri.moderation
A moderation event scoped to the community that owns this repo. Acts as an append-only audit log; current state is derived from the action history per subject.
The type of the record.
The moderation action being recorded.
Optional human-readable reason for the action.
DID of the issuer (typically a member with the required permission).
Target of the moderation action. Use `did` for user-targeted actions, `uri` for content-targeted actions.
Shared definitions
Section titled “Shared definitions”Reusable object definitions (*.defs) referenced by records, queries, and
events across the other lexicons.
social.colibri.richtext.facet
A rich text facet annotation on a message.
The features of this facet.
Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-based, counting bytes of the UTF-8 encoded text.
The start index of the byte slice (inclusive).
The end index of the byte slice (exclusive).
A facet feature for a channel reference.
The record key of the referenced channel.
A facet feature for bold text.
A facet feature for italic text.
A facet feature for underlined text.
A facet feature for strikethrough text.
A facet feature for inline code text.
A facet feature for a multi-line code block.
The language of the code block, if specified.
A facet feature for a block quote.
A facet feature for a heading line (levels 1–3).
The heading level.
A facet feature for a single list item line.
Whether the item belongs to an ordered (numbered) list.
A facet feature for a subtext line (small, muted).
A facet feature for inline spoiler text.
A facet feature for a user mention.
The DID of the mentioned user.
A facet feature for a hyperlink.
The URI of the link.
A facet feature for a timestamp.
The ISO 8601 timestamp.
Display style for the timestamp (mirrors Discord-style formats).
social.colibri.actor.defs
A hydrated Colibri actor: identity plus profile data.
The profile and presence data for a Colibri actor.
A user's Colibri status line.
Colibri-only profile theming.
Two-color gradient profile theme.
social.colibri.channel.defs
A hydrated message as served by the AppView.
The message this one replies to, if any. Never itself nested (the parent's own parent is omitted).
A file attached to a message.
An aggregated reaction on a message.
The authenticated user's read cursor for a channel.
Per-channel unread state for the authenticated user.
social.colibri.community.defs
Core community record data, hydrated with its AT-URI.
A community member, hydrated with their actor data.
A pending or dismissed membership application.
An invitation with its creator as a bare DID.
An invitation with its creator hydrated as an actor.
An invitation hydrated with its community's public details, for the invite accept screen.
social.colibri.embed.defs
A single GIF result.
An image referenced by link metadata.
social.colibri.notification.defs
A notification in the authenticated user's feed.
The message a notification refers to.
A minimal unseen-notification pointer.
Queries
Section titled “Queries”Read-only GET endpoints served by the AppView.
social.colibri.actor.getData
Resolves an identifier (DID or handle) to its hydrated Colibri actor data.
The DID or handle to resolve.
social.colibri.actor.listCommunities
Lists the communities the authenticated user is a member of, in their preferred sidebar order.
A community summary as seen from the member's perspective.
social.colibri.actor.listMutes
Lists the subjects the authenticated user has muted.
AT-URI of the mute record.
The muted subject (a DID).
social.colibri.channel.getChannelView
Returns the initial view of a channel: recent messages, the read cursor, and unseen notifications.
social.colibri.channel.getReadCursor
Returns the authenticated user's read cursor for a channel.
social.colibri.channel.listMessages
Lists messages in a channel, newest first, paginated.
Include hidden (moderated) messages.
social.colibri.channel.listReactions
Lists the aggregated reactions on a message.
social.colibri.channel.listUnreadStatus
Lists the unread status of every channel in a community for the authenticated user.
social.colibri.community.getData
Returns the full state of a community: metadata, categories, channels, roles, and members.
social.colibri.community.listCategories
Lists the categories of a community.
social.colibri.community.listChannels
Lists the channels of a community.
social.colibri.community.listMembers
Lists the members of a community.
social.colibri.community.listRoles
Lists the roles of a community.
social.colibri.community.listApplications
Lists pending and dismissed membership applications for a community.
social.colibri.community.listBannedUsers
Lists the banned users of a community.
social.colibri.community.getInvitation
Resolves an invitation code to its community, hydrated with the community's public details for the invite accept screen.
social.colibri.embed.getMetadata
Fetches Open Graph-style link preview metadata for a URL.
social.colibri.embed.getImage
Proxies and returns an external image, guarding against SSRF.
social.colibri.embed.searchGifs
Searches GIFs by query.
social.colibri.embed.trendingGifs
Returns trending GIFs.
social.colibri.embed.gifCategories
Lists GIF categories for the picker.
social.colibri.notification.listNotifications
Lists the authenticated user's notifications, paginated.
social.colibri.notification.getUnreadCount
Returns the count of unread notifications.
social.colibri.notification.getUnseen
Returns unseen notifications for a specific channel.
social.colibri.server.describeServer
Returns metadata describing the Colibri AppView deployment. Public and side-effect free.
Procedures
Section titled “Procedures”Mutating POST endpoints served by the AppView.
social.colibri.actor.setState
Sets the authenticated user's online presence state.
The presence state to set.
social.colibri.channel.create
Creates a channel in a category of a community.
The channel type, e.g. social.colibri.channel.text.
social.colibri.channel.update
Updates a channel's settings.
social.colibri.channel.delete
Deletes a channel.
social.colibri.channel.getVoiceToken
Mints a voice session token and server URL for joining a voice channel.
social.colibri.community.create
Creates a community, bootstrapping its DID repo with a default category, channel, owner role, and member record.
MIME type of the picture body, if provided.
Bring-your-own PDS endpoint.
Bring-your-own DID or handle.
Bring-your-own account password.
social.colibri.community.migrate
Migrates a source record into a fresh community, cloning its structure and importing its members. The 'kind' discriminator selects the migration; today only legacy communities are supported, but the endpoint is designed to host future migrations. Provisioning mirrors community.create (managed when no PDS credentials are supplied, bring-your-own otherwise).
The migration to run. 'legacy-community' migrates a pre-rework community record.
The record being migrated (e.g. the legacy community).
MIME type of the picture body, if provided.
Bring-your-own PDS endpoint.
Bring-your-own DID or handle.
Bring-your-own account password.
Maps each cloned channel from its old AT-URI to its new AT-URI.
A single channel's old AT-URI mapped to its new AT-URI.
social.colibri.community.update
Updates a community's metadata and optionally its picture.
social.colibri.community.delete
Deletes a community.
social.colibri.community.approveMembership
Approves a pending membership application, minting the member record.
social.colibri.community.dismissApplication
Dismisses a membership application without approving it.
social.colibri.community.undismissApplication
Restores a previously dismissed membership application.
social.colibri.community.registerCredentials
Registers bring-your-own PDS credentials for a community DID.
social.colibri.community.setMemberRoles
Replaces the set of roles assigned to a member.
social.colibri.community.reorderChannels
Reorders the channels within a category.
social.colibri.community.reorderCategories
Reorders the categories within a community.
social.colibri.community.banUser
Bans a user from a community.
DID or handle of the user to ban.
social.colibri.community.unbanUser
Lifts a ban on a user.
DID or handle of the user to unban.
social.colibri.community.kickUser
Kicks a user from a community by DID or handle.
DID or handle of the user to kick.
social.colibri.community.kick
Kicks a member from a community by member record.
social.colibri.community.blockMessage
Hides (moderates) a message within a community.
social.colibri.community.createInvitation
Creates an invitation code for a community.
social.colibri.community.listInvitations
Lists the active invitations of a community.
social.colibri.community.deleteInvitation
Deletes an invitation code.
social.colibri.community.leave
Leaves a community, removing the authenticated user's membership.
social.colibri.category.create
Creates a category in a community.
social.colibri.category.update
Renames a category.
social.colibri.category.delete
Deletes a category.
social.colibri.role.create
Creates a role in a community.
social.colibri.role.update
Updates a role.
social.colibri.role.delete
Deletes a role.
social.colibri.notification.updateSeen
Marks all notifications up to a timestamp as seen.
Defaults to now if omitted.
social.colibri.notification.updateSeenForMessage
Marks notifications for a specific message as seen.
social.colibri.notification.registerPush
Registers a Web Push subscription for the authenticated user.
Web Push subscription keys.
social.colibri.notification.unregisterPush
Removes a Web Push subscription.
social.colibri.sync.sendHum
Informs this AppView of an off-protocol event that occurred on a peer AppView. Requires inter-service auth: a JWT signed by the caller's AppView signing key, aud = this AppView's did:web, lxm = social.colibri.sync.sendHum. The receiver drops the Hum unless the JWT issuer equals both the envelope `origin` and the `subject`'s declared presenceService.
Missing or invalid service-auth JWT.
A trust-model check failed (origin is not the subject's declared presenceService, subject is not a community member, origin is not an AppView, or a channel does not belong to the community).
Event type is not an off-protocol Hum event.
The peer exceeded its per-peer sendHum rate budget.
Humming is disabled on this AppView.
Subscriptions
Section titled “Subscriptions”WebSocket event streams.
social.colibri.sync.subscribeEvents
Opens a WebSocket stream that transmits relevant events for the authenticated user.
Sent in response to a heartbeat message.
Sent when a community has been updated or deleted.
Sent when a member has joined or left a community.
Sent when a category has been created, updated, or deleted.
Sent when a channel has been created, updated, or deleted.
Sent when a message has been sent, edited, or deleted.
Sent when a reaction has been added to or removed from a message.
Sent when a known user has updated their profile or Colibri status.
Sent when a user is typing in a channel the client is viewing.
Sent when a user joins or leaves a voice channel.
An off-protocol event relayed between AppViews. The authenticated sender (inter-service auth JWT: aud = receiving AppView did:web, lxm = social.colibri.sync.sendHum) is the origin of record; `origin` is echoed for relay/loop control and MUST match the JWT issuer. Only off-protocol event types are permitted — on-protocol events are never carried by a Hum and are derived from the firehose instead.
DID of the AppView that first emitted this Hum.
Unique id for this Hum, used by receivers to dedup across relay paths.
Remaining relay hops. Decremented on each forward; a Hum at ttl 0 is delivered locally but never relayed.
The user this event is about. Receiver MUST verify origin equals subject's declared presenceService before trusting or relaying.
Community the event is scoped to. Receiver relays to local clients only if they are members of this community.
Ephemeral event payload. Only off-protocol types are permitted.
social.colibri.sync.subscribeHums
Egress-only WebSocket stream of Hums this AppView is relaying. Peers subscribe to receive off-protocol events for shared communities, optionally narrowing to declared `communities` (repeated query param). Requires inter-service auth (subprotocol-carried, as with subscribeEvents). Clients cannot send messages on this stream.
Humming is disabled on this AppView.
The hub is at its subscribeHums connection limit.
Permission sets
Section titled “Permission sets”OAuth permission sets bundling the scopes a client can request.
social.colibri.permissionAccount
Manage your Colibri profile, status, and mutes, and receive realtime updates.
- social.colibri.actor.data
- social.colibri.actor.profile
- social.colibri.actor.mute
- social.colibri.actor.gifFavorites
- social.colibri.actor.getData
- social.colibri.actor.listCommunities
- social.colibri.actor.listMutes
- social.colibri.actor.setState
- social.colibri.sync.subscribeEvents
- social.colibri.sync.sendHum
social.colibri.permissionCommunity
Create and manage communities, categories, channels, and roles, including moderation and invitations.
- social.colibri.community
- social.colibri.category
- social.colibri.channel
- social.colibri.role
- social.colibri.channel.read
- social.colibri.community.create
- social.colibri.community.migrate
- social.colibri.community.update
- social.colibri.community.delete
- social.colibri.community.registerCredentials
- social.colibri.community.approveMembership
- social.colibri.community.listApplications
- social.colibri.community.dismissApplication
- social.colibri.community.undismissApplication
- social.colibri.community.kick
- social.colibri.community.kickUser
- social.colibri.community.setMemberRoles
- social.colibri.community.leave
- social.colibri.community.reorderChannels
- social.colibri.community.reorderCategories
- social.colibri.community.blockMessage
- social.colibri.community.banUser
- social.colibri.community.unbanUser
- social.colibri.community.createInvitation
- social.colibri.community.listInvitations
- social.colibri.community.deleteInvitation
- social.colibri.category.create
- social.colibri.category.update
- social.colibri.category.delete
- social.colibri.channel.create
- social.colibri.channel.update
- social.colibri.channel.delete
- social.colibri.channel.getReadCursor
- social.colibri.channel.listUnreadStatus
- social.colibri.channel.getVoiceToken
- social.colibri.role.create
- social.colibri.role.update
- social.colibri.role.delete
- social.colibri.embed.getMetadata
- social.colibri.embed.searchGifs
- social.colibri.embed.trendingGifs
- social.colibri.embed.gifCategories
- social.colibri.community.getData
- social.colibri.community.listBannedUsers
- social.colibri.community.listCategories
- social.colibri.community.listChannels
- social.colibri.community.listMembers
- social.colibri.community.listRoles
- social.colibri.community.getInvitation
- social.colibri.channel.listMessages
- social.colibri.channel.getChannelView
social.colibri.permissionMessaging
Send and edit messages, react, join communities, and submit membership applications.
- social.colibri.message
- social.colibri.membership
- social.colibri.approval
- social.colibri.reaction
- social.colibri.channel.listReactions
social.colibri.permissionNotification
Read your notifications and mark them as seen.
- social.colibri.notification.listNotifications
- social.colibri.notification.getUnreadCount
- social.colibri.notification.updateSeen
- social.colibri.notification.updateSeenForMessage
- social.colibri.notification.getUnseen
social.colibri.permissionPush
Manage your push notification subscriptions.
- social.colibri.notification.registerPush
- social.colibri.notification.unregisterPush
Colibri-only profile theming.
Accent color as a #rrggbb hex string.
Two-color gradient profile theme.
Solid fallback banner color as #rrggbb, used when no banner image is set.