gRPC API
A Polycentric server exposes its API as gRPC services in the polycentric.v2
package, served as gRPC (HTTP/2 cleartext) and gRPC-Web on one port (3000 by
default, see Host a Server).
The reference below is generated when this site is built from the .proto
files in
protos/polycentric/v2,
so it matches the checked-in definitions. Every server also serves the
reference for its own build at /docs, generated from gRPC reflection.
Calling a method
- Path. A method is
POST /{package}.{Service}/{Method}, for examplehttps://srv.harbor.social/polycentric.v2.FeedsService/GetExploreFeed. - Encoding. Requests and responses are binary protobuf messages. The Try
it out panels below take
proto3 JSON (
bytesfields are base64, 64-bit integers may be strings), encode it, and send a real gRPC-Web request from your browser to the selected server. - Authentication. Methods that act for an identity expect a JWT in the
authorizationheader, see Server Authentication. Push notification registration instead takes aSignedMessageenvelope signed by the device's key pair. - Reflection. Servers enable gRPC reflection, so tools like grpcurl can list and call methods without the proto files:
grpcurl -plaintext localhost:3000 list
grpcurl -plaintext -d '{"identity": "<identity>"}' localhost:3000 \
polycentric.v2.ProfileService/GetProfile
The messages carried by events (posts, follows, identity documents and so on) are explained in Data Model. Blob bodies are downloaded over plain HTTP, see the HTTP endpoints.
ContentService
polycentric.v2.ContentService in content.proto
SyncContent
POST /polycentric.v2.ContentService/SyncContent
gRPC requests
Digest that was created from the serialized content_bytes
Serialized Content message
No fields.
UploadBlob
Uploads a blob. If the blob is not referenced by an event within a time window, it will be deleted. Blob bodies are served back over plain HTTP at GET /blob/{digest}.
POST /polycentric.v2.ContentService/UploadBlob
Request message for uploading a blob
Reference message of the blob (mime type, content digest).
Body (content) of the blob
No fields.
UrlInfo
Fetches a URL server-side and returns its link preview metadata.
POST /polycentric.v2.ContentService/UrlInfo
Request message for fetching link metadata for a URL.
The URL to fetch metadata for.
Response for UrlInfo: the fetched link-preview metadata.
EventSyncService
Sync between clients and servers
polycentric.v2.EventSyncService in events.proto
ListEvents
Returns a list of events (with content) from the server
POST /polycentric.v2.EventSyncService/ListEvents
Filters
Max number of events to return
PutEvents
Add events (with content) from a client to the server
POST /polycentric.v2.EventSyncService/PutEvents
One entry per event the server could not store. Any error in here means the event was not stored.
Empty when every event in the request was accepted.
Blobs referenced by the events that the server does not have. Client should upload these.
Zero or more entries per event that caused the content of the event not be stored, the event data is still stored. For example if this contains a warning that the event's application name is too long the event will be stored, but the application will not.
Empty when every event and its content in the request was accepted.
ListHeads
Returns the latest sequence number seen by the server for each (signing key, collection) for the given identity
POST /polycentric.v2.EventSyncService/ListHeads
Each event key represents the greatest sequence number with the same (identity, public key, collection) known by this server
GetReactions
Get the reactions targeting an event.
POST /polycentric.v2.EventSyncService/GetReactions
Event key of the event to get reactions for
Return only reactions with this emoji set
GetAttributedToReactionCounts
Get the reaction counts for an out-of-network target (e.g. a video URL).
POST /polycentric.v2.EventSyncService/GetAttributedToReactionCounts
The attributed target (e.g. a video URL) to get reaction counts for.
The server's estimate for positive reactions on the target.
The server's estimate for negative reactions on the target.
FeedsService
Curated feeds provided by servers
polycentric.v2.FeedsService in feeds.proto
GetIdentityFeed
Posts that belong to an identity
POST /polycentric.v2.FeedsService/GetIdentityFeed
Identity to return the posts of
Label values for which the requester does not want to see content
GetFollowingFeed
Get posts created by the identity themselves and all identities they follow.
POST /polycentric.v2.FeedsService/GetFollowingFeed
Identity of the follower to return the feed for
Label values for which the requester does not want to see content
GetRecommendedFeed
Get posts created by, reacted to, reposted by, quoted or replied to by the identity themselves and all identities they follow.
POST /polycentric.v2.FeedsService/GetRecommendedFeed
Identity of the follower to return the feed for
Label values for which the requester does not want to see content
GetExploreFeed
Get posts by any identity.
POST /polycentric.v2.FeedsService/GetExploreFeed
Identity of the caller to return relevant posts for
Label values for which the requester does not want to see content
GetPost
Get a single post.
POST /polycentric.v2.FeedsService/GetPost
Request candidate posts matching these filters.
All candidate post events matching the request's filter.
GetPostThread
Replies to a post.
POST /polycentric.v2.FeedsService/GetPostThread
Parent post to return the thread for
Label values for which the requester does not want to see content
GetAttributionFeed
Posts attributed to the same target (e.g. all posts about a URL)
POST /polycentric.v2.FeedsService/GetAttributionFeed
Attribution to match posts against. A post is included when any of its attributed_to entries is similar to this one — for a link, similar means the same URL, ignoring other Link metadata.
Label values for which the requester does not want to see content
GraphService
polycentric.v2.GraphService in graph_service.proto
ListFollowing
Follow events authored by identity — who they follow.
POST /polycentric.v2.GraphService/ListFollowing
Identity whose followed identities are returned.
The active (non-tombstoned) Follow events, newest first.
Relevant events for the users in the follow events
ListFollowers
Follow events targeting identity — who follows them.
POST /polycentric.v2.GraphService/ListFollowers
Identity whose followers are returned.
The active (non-tombstoned) Follow events, newest first.
Relevant events for the users in the follow events
SuggestFollow
Suggestion what identities to follow.
POST /polycentric.v2.GraphService/SuggestFollow
Contains profile update events for the suggested to-follow identities (FollowSuggestion.suggestion). Note that the identity events for the to-follow identities can be found in the suggestions.
Also contains identity, profile update and follow events for the suggested the identities of those who already follow those identities (FollowSuggestion.followers).
IdentityService
Identity moderation APIs. The caller is authenticated by its bearer JWT (see auth_middleware); the ban endpoints require a moderator.
polycentric.v2.IdentityService in identity_service.proto
IsModerator
Returns whether the calling identity is a moderator on this server.
POST /polycentric.v2.IdentityService/IsModerator
IsModerator: no extra fields.
No fields.
SetBanStatus
Bans or unbans an identity on this server.
POST /polycentric.v2.IdentityService/SetBanStatus
SetBanStatus: ban or unban an identity.
Identity key being banned or unbanned.
Desired ban state: true to ban, false to unban.
No fields.
IsBanned
Returns whether an identity is banned on this server.
POST /polycentric.v2.IdentityService/IsBanned
IsBanned: query whether an identity is banned.
Identity key being asked about.
ListBans
Lists the identities banned on this server.
POST /polycentric.v2.IdentityService/ListBans
ListBans: paginated, optionally filtered list of banned identities.
Max entries to return; the server clamps to its own bounds.
Opaque cursor from a previous response's page_info.end_cursor.
Case-insensitive prefix filter: keep only identities beginning with this value.
Identity keys banned on this server, most recently banned first.
NotificationService
Notifications for an identity. ListNotifications, AcknowledgeNotifications and SubscribeUnreadNotificationCount are served by the server. The push registration methods are served by a push-notifications service; a server without one answers them with NOT_FOUND.
polycentric.v2.NotificationService in notifications.proto
ListNotifications
Returns notifications for a user
POST /polycentric.v2.NotificationService/ListNotifications
Return the 1 X number of notifications
Return notifications after a cursor
Label values for which the requester does not want to see content
Events that help the client resolve with fewer network calls
AcknowledgeNotifications
Marks the authenticated identity's notifications up to last_seen as read
POST /polycentric.v2.NotificationService/AcknowledgeNotifications
The identity comes from the auth token
Trigger event of the newest notification the client has shown. Every notification up to it is marked read, later ones stay unread. A server that does not hold that notification marks everything it has
Empty: success is signalled by the call not failing
No fields.
SubscribeUnreadNotificationCount
Streams the unread notification count of the authenticated identity, now and whenever it changes
POST /polycentric.v2.NotificationService/SubscribeUnreadNotificationCountserver streaming
Empty: the identity comes from the auth token
No fields.
Unread count for the authenticated identity on this server, sent on subscribe and again whenever it changes
Notifications newer than the last acknowledgement, capped by the server
RegisterPushNotifications
This endpoint expects a signed RegisterPushNotificationRequest message
POST /polycentric.v2.NotificationService/RegisterPushNotifications
Envelope for requests authenticated with a key pair instead of a bearer token.
Signature by public_key over message_bytes.
The serialized request message, e.g. a RegisterPushNotificationRequest.
No fields.
UnregisterPushNotifications
This endpoint expects a signed UnregisterPushNotificationRequest message
POST /polycentric.v2.NotificationService/UnregisterPushNotifications
Envelope for requests authenticated with a key pair instead of a bearer token.
Signature by public_key over message_bytes.
The serialized request message, e.g. a RegisterPushNotificationRequest.
No fields.
PairingService
Pairing APIs used for device pairing: linking a new device (the claimer) to an existing identity (the issuer).
The issuer creates a session with PutPairingSession by uploading its first SignedIssuerState. The session is addressed by the SHA-256 of the serialized PairingSessionDigest inside that state. The issuer shares a PairingInfo (server URL and digest hash) with the claimer out-of-band, for example as a QR code. The claimer fetches the session with GetPairingSession, checks that the digest hashes to the shared value and that the issuer state is signed by issuer_signer, then registers its key with JoinPairingSession. The issuer polls GetPairingSession for claimers, authorizes the claimer's key in a new identity event and uploads it in its next issuer state, which the claimer polls for.
polycentric.v2.PairingService in pairing_service.proto
PutPairingSession
Creates or updates a pairing session after authorizing the request as valid.
POST /polycentric.v2.PairingService/PutPairingSession
Wrapper request for PutPairingSession RPC.
Wrapper response for PutPairingSession RPC.
GetPairingSession
Fetch a pairing session.
POST /polycentric.v2.PairingService/GetPairingSession
Request payload for fetching a pairing session.
Wrapper response for GetPairingSession RPC.
JoinPairingSession
Registers a claimer to a pairing session.
POST /polycentric.v2.PairingService/JoinPairingSession
Wrapper request for JoinPairingSession RPC.
SHA256 of the pairing session digest to join.
Public key that the claimer wishes to join with.
Wrapper response for JoinPairingSession RPC.
ProfileService
polycentric.v2.ProfileService in profile_service.proto
GetProfile
A profile with its aggregate counters.
POST /polycentric.v2.ProfileService/GetProfile
The identity's latest profile events.
Side information needed to validate the bundles (the identity's key chain).
Distinct identities this identity follows.
Distinct identities following this identity.
SearchService
polycentric.v2.SearchService in search.proto
SearchUsers
Search users.
POST /polycentric.v2.SearchService/SearchUsers
Relevant search results.
Relevant events for the events in the search results.
SearchPosts
Search posts.
POST /polycentric.v2.SearchService/SearchPosts
Label values for which the requester does not want to see content.
Relevant search results.
Relevant events for the events in the search results.
ServerService
polycentric.v2.ServerService in server.proto
GetInfo
Returns relevant information about a server
POST /polycentric.v2.ServerService/GetInfo
No fields.
VerificationsService
polycentric.v2.VerificationsService in verifications_service.proto
ListVerificationClaims
VerificationClaim events published by an identity, with each claim's targets and verifies.
POST /polycentric.v2.VerificationsService/ListVerificationClaims
Additional events that may be helpful, like relevant identity and profiles
ListVerificationTargets
VerificationTarget events for a claim: who has been asked to verify.
POST /polycentric.v2.VerificationsService/ListVerificationTargets
VerificationTarget events for the claim, published by the claim's owner — who has been asked to verify.
Additional events that may be helpful, like relevant identity and profiles
ListVerificationVerifies
VerificationVerify events for a claim: who has verified it.
POST /polycentric.v2.VerificationsService/ListVerificationVerifies
VerificationVerify events for the claim.
Additional events that may be helpful, like relevant identity and profiles
ListTargetedVerificationClaims
Claims whose owner asked target_identity for verification, with each claim's targets and verifies.
POST /polycentric.v2.VerificationsService/ListTargetedVerificationClaims
Claims whose owner targeted target_identity. The 'inbox'.
Additional events that may be helpful, like relevant identity and profiles
ResolveVerifiedClaims
Reverse lookup: claims matching the given schema + field values that are verified by a trusted identity, with each claim's targets and verifies.
POST /polycentric.v2.VerificationsService/ResolveVerifiedClaims
Reverse lookup: find the identities that claim something, starting from the claim's field values rather than from an identity. Answers "who claims this (e.g. this platform channel, this occupation), verified by a trusted party?" — the inverse of the identity-keyed queries above. Works for any claim type.
Optional type scope: restrict to claims of exactly this schema, by the schema's content digest. Unset (or empty value) = any schema. This is the schema's content-addressed identifier; it only groups cross-client when claimants pin identical canonical schema bytes.
Field key/value pairs a claim's (STRING) fields must contain, matched by JSONB containment. A claim matches only when it contains every supplied pair (AND); it may carry additional fields. A claim missing any supplied field does not match. May be empty when schema_digest scopes the query.
Only return claims that carry a VerificationVerify authored by one of these identities (the trust roots). Required and non-empty — this is what makes a match "verified" rather than merely "claimed".
Matching claims, each wrapped with its targets and verifies (the verifies include at least one authored by a trusted identity).
Additional events that may be helpful, like relevant identity and profiles
Schemas
Every message and enum of the polycentric.v2 package, by file. Type names in the field lists above link here.
backup.proto
IdentityBackupMessage to hex-encode and store securely for account recovery.
Message to hex-encode and store securely for account recovery.
The hex string of the identity.
The signed events for the canonical identity chain at the time of creating this backup.
The private key corresponding to the recovery public key in the latest identity document.
common.proto
PageInfoReturned by paginated feeds to aid in future queries.
Returned by paginated feeds to aid in future queries.
Opaque string that can be included in a request to the server to receive the previous page of data.
Opaque string that can be included in a request to the server to receive the next page of data.
True if there is likely more data preceding start_cursor.
True if there is likely more data following end_cursor.
PageParamsSent by clients to servers for fetching paginated data.
Sent by clients to servers for fetching paginated data.
Max events to return.
Request data preceding this start cursor in the feed.
Request data following this end cursor in the feed.
ContentDigest
We hash the serialized bytes
ContentDigestTypeenum
content.proto
ContentContent of the event
Content of the event
Verifications (see verifications.proto)
SerializedContentSerialized content.
Serialized content. This is what we do the ContentDigest / Checksum on.
Post
Main text content of the post
Multiple images
Link previews for URLs in the post text
Labels the creator / client applies themselves
If any, where the post is attributed to.
AttributedTo
Remote resource
PostReply
Initial post in the reply chain.
Post that is being replied to
Link
Repost
DeleteWhen processed by a server it should check if the data is referenced by any events If the Content is linked elswhere, the DELETE is ignored and the server should keep the data.
When processed by a server it should check if the data is referenced by any events If the Content is linked elswhere, the DELETE is ignored and the server should keep the data. If the Content is not linked elsewhere then it can be deleted / purged by the server. Essentially, a DELETE means; Ignore (or forget about) the contents of a previous event.
Event key to be deleted
Follow
Block
Reaction
Key of the event being reacted to
Optional emoji
Upvote = true. Downvote = false.
AttributedToReactionA reaction targeting something that is not an in-network event — e.g. a URL (reacting to a video).
A reaction targeting something that is not an in-network event — e.g. a URL (reacting to a video). The out-of-network counterpart of Reaction.
What the reaction is attributed to (e.g. a link/URL).
Optional emoji
Upvote = true. Downvote = false.
ProfileUpdate
A friendly display name for the user
Reference to the Blob for the avatar (support multiple different sizes)
Reference to the Blob of a banner (support multiple different sizes)
Bio
A domain-based alias (e.g. [email protected]) the profile claims for itself.
BlobIf an uploaded Blob is uploaded to the servers Object Storage and not then attached added to the Content repository, the server will delete from Object Storage.
If an uploaded Blob is uploaded to the servers Object Storage and not then attached added to the Content repository, the server will delete from Object Storage.
Digest/Checksum of the blob
ImageSingle image with reference to the blob
Single image with reference to the blob
ImageSetCollection of different variants of an image
Collection of different variants of an image
Report
Event that is being reported
Labels
Event that is being labeled
SyncContentRequestgRPC requests
gRPC requests
Digest that was created from the serialized content_bytes
Serialized Content message
SyncContentResponse
No fields.
UploadBlobRequestRequest message for uploading a blob
Request message for uploading a blob
Reference message of the blob (mime type, content digest).
Body (content) of the blob
UploadBlobResponse
No fields.
UrlInfoRequestRequest message for fetching link metadata for a URL.
Request message for fetching link metadata for a URL.
The URL to fetch metadata for.
UrlInfoResponseResponse for UrlInfo: the fetched link-preview metadata.
Response for UrlInfo: the fetched link-preview metadata.
ReportCategoryenum
event_key.proto
EventKeyEventKey's are the unique identitifiers of Events
EventKey's are the unique identitifiers of Events
Collection of the stream the event is connected with Reserved collections are:
1 -> Polycentric Identity 2 -> Polycentric feed 3 -> Polycentric profile 4 -> Polycentric interactions (likes etc) 5 -> Polycentric social graph (follows) 6 -> Polycentric reports 7 -> Polycentric labels 8 -> Polycentric verifications
Identity Key (sha256 hash of the initial Identity content)
Public key that signed the event
Sequence number of the event in the collection (our logical clock)
events.proto
VectorClockContains the sequences (of the same event collection) that the current KeyPair is aware of.
Contains the sequences (of the same event collection) that the current KeyPair is aware of. The order of the sequences is determined by the keys listed in the relevant identity document: The rotation keys first and then the signing keys, with duplicates skipped when they appear again. Use Identity::deduplicated_keys() to get the keys in this order.
ApplicationThe application that authored an event.
The application that authored an event.
Human-readable name, e.g. "Harbor".
Reverse-DNS package or bundle identifier, e.g. "org.futo.polycentric".
Version of the application, e.g. "1.2.0".
Website of the application, e.g. "https://harbor.social".
EventEvent messages reference, but do not include, content
Event messages reference, but do not include, content
Key for the event
Reference to the sequence, of the Identity Collection (1), that holds the identity document
Vector clock
Signature of the previous event signed by the same key. Assists in creating immutable collections.
Digest of the content
Timestamp, in milliseconds, of when the event was created
RFC 6962 Merkle root over this signer's prior signatures in this collection (leaf_count = key.sequence - 1). Lets later events attest to the writer's history; consumed by EventProof for membership verification.
The application that created the event. Absent when unknown.
SignedEvent
Signature of events_bytes below (not the Event message)
Serialized representation of the Event message that is signed against
EventBundleBundle of the SignedEvent and SerializedContent messages We use SerializedContent so that the checksum of the content can be verified
Bundle of the SignedEvent and SerializedContent messages We use SerializedContent so that the checksum of the content can be verified
EventProofMerkle inclusion proof: the SignedEvent in this bundle is the leaf at `leaf_index` in the tree rooted at the `EventProofTarget` identified by `target_signature`.
Merkle inclusion proof: the SignedEvent in this bundle is the leaf at leaf_index in the tree rooted at the EventProofTarget identified by target_signature.
Canonical position of this event in the target's tree.
RFC 6962 audit path: sibling hashes from leaf toward root.
EventMetadataOptional helper data that servers can include to help clients better present information to users.
Optional helper data that servers can include to help clients better present information to users.
This server's estimate for how many replies a post has.
This server's estimate for the total number of reactions a post has.
This server's estimate for the total number of positive reactions a post has.
This server's estimate for the total number of negative reactions a post has.
This server's estimate for the count for each reaction type a post has.
ReactionTallyConveys the number of times a specific reaction was given.
Conveys the number of times a specific reaction was given.
EventHintHints are additional events that the server provides that may be useful to the client and avoid additional network requests.
Hints are additional events that the server provides that may be useful to the client and avoid additional network requests. For example, a reply to post event could return the root/parent posts along with the most recent profile event
ListEventsFilters
Collection to filter events by
Identity key to filter events by
Filter events to those signed by this public key
Return sequences greater than
Return sequences less than
When an event matches a head's identity, collection, and signer, only return it if its sequence number is higher than the head
ListEventsRequest
Filters
Max number of events to return
ListEventsResponse
PutEventsRequest
PutEventErrorPer-event failure reported by PutEvents.
Per-event failure reported by PutEvents. The call as a whole still succeeds — these entries are diagnostic for events the server skipped.
Index of the failed entry in PutEventsRequest.event_bundles.
Human-readable reason mirroring the gRPC Status ingest would otherwise have returned for this event in isolation.
PutEventsResponse
One entry per event the server could not store. Any error in here means the event was not stored.
Empty when every event in the request was accepted.
Blobs referenced by the events that the server does not have. Client should upload these.
Zero or more entries per event that caused the content of the event not be stored, the event data is still stored. For example if this contains a warning that the event's application name is too long the event will be stored, but the application will not.
Empty when every event and its content in the request was accepted.
ListHeadsRequest
ListHeadsResponse
Each event key represents the greatest sequence number with the same (identity, public key, collection) known by this server
GetReactionsRequest
Event key of the event to get reactions for
Return only reactions with this emoji set
GetReactionsResponse
GetAttributedToReactionCountsRequest
The attributed target (e.g. a video URL) to get reaction counts for.
GetAttributedToReactionCountsResponse
The server's estimate for positive reactions on the target.
The server's estimate for negative reactions on the target.
feeds.proto
GetIdentityFeedRequest
Identity to return the posts of
Label values for which the requester does not want to see content
GetFollowingFeedRequest
Identity of the follower to return the feed for
Label values for which the requester does not want to see content
GetExploreFeedRequest
Identity of the caller to return relevant posts for
Label values for which the requester does not want to see content
GetFeedResponse
GetPostThreadResponse
GetPostRequestRequest candidate posts matching these filters.
Request candidate posts matching these filters.
GetPostResponseAll candidate post events matching the request's filter.
All candidate post events matching the request's filter.
GetPostThreadRequest
Parent post to return the thread for
Label values for which the requester does not want to see content
GetAttributionFeedRequest
Attribution to match posts against. A post is included when any of its attributed_to entries is similar to this one — for a link, similar means the same URL, ignoring other Link metadata.
Label values for which the requester does not want to see content
FeedAlgorithmenum
graph_service.proto
ListFollowingRequest
Identity whose followed identities are returned.
ListFollowersRequest
Identity whose followers are returned.
SuggestFollowRequest
ListFollowsResponse
The active (non-tombstoned) Follow events, newest first.
Relevant events for the users in the follow events
SuggestFollowResponse
Contains profile update events for the suggested to-follow identities (FollowSuggestion.suggestion). Note that the identity events for the to-follow identities can be found in the suggestions.
Also contains identity, profile update and follow events for the suggested the identities of those who already follow those identities (FollowSuggestion.followers).
FollowSuggestion
Identity (event) to follow.
Identities that are following the suggested identity.
identity_service.proto
IsModeratorRequestIsModerator: no extra fields.
IsModerator: no extra fields.
No fields.
IsModeratorResponse
SetBanStatusRequestSetBanStatus: ban or unban an identity.
SetBanStatus: ban or unban an identity.
Identity key being banned or unbanned.
Desired ban state: true to ban, false to unban.
SetBanStatusResponse
No fields.
IsBannedRequestIsBanned: query whether an identity is banned.
IsBanned: query whether an identity is banned.
Identity key being asked about.
IsBannedResponse
ListBansRequestListBans: paginated, optionally filtered list of banned identities.
ListBans: paginated, optionally filtered list of banned identities.
Max entries to return; the server clamps to its own bounds.
Opaque cursor from a previous response's page_info.end_cursor.
Case-insensitive prefix filter: keep only identities beginning with this value.
ListBansResponse
Identity keys banned on this server, most recently banned first.
identity.proto
Identity
List of the currently-active rotation keys. These keys can publish events, including identity events with updates made to the identity document.
List of keys that are allowed to sign events (but not change the identity content).
In order to retain valid events from a revoked keypair, we store their last known signature for each collection the key participated in.
Preferred servers of this identity (where they push and pull from). Absent means the identity has not configured a server list yet and clients fall back to their defaults; present-but-empty is intentional.
Backup key for recovering an account with no active sessions. Its only use is for producing recovery signatures.
Signature from the recovery key in the preceding identity document. The content signed should be (identity_string, new_rotation_key).
ServerList
RevocationBound
Key that is revoked
One target per collection revoked_key wrote in, anchoring proof verification at that collection's head event.
EventProofTargetPer-collection target for verifying an EventProof.
Per-collection target for verifying an EventProof.
Event's signature; matched by EventProof.target_signature.
Event's previous_root — the Merkle root proofs verify against.
Leaf count of the tree at root (the number of events the head's signer was aware of when they signed it).
keypair.proto
PublicKeyPublicKeys signs all events on the polycentric network.
PublicKeys signs all events on the polycentric network. There is usually one public key per account, per device.
Type of key used. Defaults to ED25519.
Value of the key
PrivateKeyThe private key corresponding to a public key.
The private key corresponding to a public key.
Type of key used. Defaults to ED25519.
Value of the key
KeyTypeenum
notifications.proto
Notification
Event that triggered the notification
Event that the notification is in relation to
Kind of the notification
ListNotificationsRequest
Return the 1 X number of notifications
Return notifications after a cursor
Label values for which the requester does not want to see content
ListNotificationsResponse
Events that help the client resolve with fewer network calls
AcknowledgeNotificationsRequestThe identity comes from the auth token
The identity comes from the auth token
Trigger event of the newest notification the client has shown. Every notification up to it is marked read, later ones stay unread. A server that does not hold that notification marks everything it has
AcknowledgeNotificationsResponseEmpty: success is signalled by the call not failing
Empty: success is signalled by the call not failing
No fields.
SubscribeUnreadNotificationCountRequestEmpty: the identity comes from the auth token
Empty: the identity comes from the auth token
No fields.
SubscribeUnreadNotificationCountResponseUnread count for the authenticated identity on this server, sent on subscribe and again whenever it changes
Unread count for the authenticated identity on this server, sent on subscribe and again whenever it changes
Notifications newer than the last acknowledgement, capped by the server
RegisterPushNotificationRequest
Push provider the token belongs to. expo is the only provider currently supported.
Device token issued by the push provider.
RegisterPushNotificationResponse
No fields.
UnregisterPushNotificationRequest
Push provider the token belongs to, see RegisterPushNotificationRequest.
UnregisterPushNotificationResponse
No fields.
NotificationKindenum
pairing_service.proto
PairingSessionDigestImmutable state created at the start of a pairing session that uniquely identifies it.
Immutable state created at the start of a pairing session that uniquely identifies it.
Trusted source of truth for the identity being paired with.
Each issuer state must be signed by this key and this key must be authorized for rotation.
Random bitstring to add entropy and keep session identifiers unpredictable.
Timestamp in posix epoch millis. Used for expiration and preventing replay attacks.
The number of milliseconds after the initial timestamp for which this session is considered valid.
PairingInfoData to share out-of-band between the issuer and claimer.
Data to share out-of-band between the issuer and claimer. This means using copy/paste or a QR code.
URL of the server that holds this pairing session.
SHA256 hash of the pairing session digest.
IssuerPairingStateSigned payload from issuers that contains pairing state information.
Signed payload from issuers that contains pairing state information. Contains authenticated information about the pairing session for claimers and servers to read. Clients and servers should only obtain messages of this type from a SignedIssuerState message and must check its signature.
Serialized PairingSessionDigest message. Identifies the pairing session that this state belongs to. This should be kept constant throughout the session. Clients should verify that the SHA256 hash and content of this field matches what they expect.
The most recent identity event for this identity as reported by the issuer. Claimers should verify the full identity chain before fully trusting the content of this field. Even when not fully trusted, it is still useful for:
- seeding the list of servers to query.
- deciding when to try claiming.
A counter that gets incremented for each new state in this pairing session. This keeps updates well-ordered and prevents replay attacks from rolling back state. Starts at 1 for each pairing session.
SignedIssuerStateEncapsulates an issuer's signed pairing state and its signature.
Encapsulates an issuer's signed pairing state and its signature.
Serialized IssuerPairingState message from the issuer.
Signature over state_bytes. Must use the key pair specified in the digest.
PairingSessionStateServer-aggregated state for a pairing session containing input from the issuer and claimers.
Server-aggregated state for a pairing session containing input from the issuer and claimers.
Server-managed list of claimers.
GetPairingSessionRequestRequest payload for fetching a pairing session.
Request payload for fetching a pairing session.
PutPairingSessionRequestWrapper request for PutPairingSession RPC.
Wrapper request for PutPairingSession RPC.
PutPairingSessionResponseWrapper response for PutPairingSession RPC.
Wrapper response for PutPairingSession RPC.
GetPairingSessionResponseWrapper response for GetPairingSession RPC.
Wrapper response for GetPairingSession RPC.
JoinPairingSessionRequestWrapper request for JoinPairingSession RPC.
Wrapper request for JoinPairingSession RPC.
SHA256 of the pairing session digest to join.
Public key that the claimer wishes to join with.
JoinPairingSessionResponseWrapper response for JoinPairingSession RPC.
Wrapper response for JoinPairingSession RPC.
profile_service.proto
GetProfileRequest
GetProfileResponse
The identity's latest profile events.
Side information needed to validate the bundles (the identity's key chain).
Distinct identities this identity follows.
Distinct identities following this identity.
search.proto
SearchUsersRequest
SearchPostsRequest
Label values for which the requester does not want to see content.
SearchUsersResponse
Relevant search results.
Relevant events for the events in the search results.
SearchPostsResponse
Relevant search results.
Relevant events for the events in the search results.
SearchResult
Search rank, higher means more relevant.
SortUsersByenum
Default sorting by relevancy.
Alphabetic order of profile name.
SortPostsByenum
Default sorting by relevancy.
Top post first.
Latests post first.
server.proto
ServerVersionCurrent version the server is running on.
Current version the server is running on.
ServerInfoRelevant information about the current server, such as version, public endpoints, etc.
Relevant information about the current server, such as version, public endpoints, etc.
URL used to resolve HTTP assets (blobs, images, etc), the server's HARBOR_CDN_URL setting.
GetServerInfoRequest
No fields.
GetServerInfoResponse
SignedMessageEnvelope for requests authenticated with a key pair instead of a bearer token.
Envelope for requests authenticated with a key pair instead of a bearer token.
Signature by public_key over message_bytes.
The serialized request message, e.g. a RegisterPushNotificationRequest.
verifications_service.proto
VerificationClaimBundleA claim with the verification state around it, so lists can show each claim's verified status from a single response.
A claim with the verification state around it, so lists can show each claim's verified status from a single response.
The VerificationClaim event.
VerificationTarget events published by the claim's owner
VerificationVerify events.
ListVerificationClaimsRequest
ListVerificationClaimsResponse
Additional events that may be helpful, like relevant identity and profiles
ListVerificationTargetsRequest
ListVerificationTargetsResponse
VerificationTarget events for the claim, published by the claim's owner — who has been asked to verify.
Additional events that may be helpful, like relevant identity and profiles
ListVerificationVerifiesRequest
ListVerificationVerifiesResponse
VerificationVerify events for the claim.
Additional events that may be helpful, like relevant identity and profiles
ListTargetedVerificationClaimsRequest
ListTargetedVerificationClaimsResponse
Claims whose owner targeted target_identity. The 'inbox'.
Additional events that may be helpful, like relevant identity and profiles
ResolveVerifiedClaimsRequestReverse lookup: find the identities that claim something, starting from the claim's field values rather than from an identity.
Reverse lookup: find the identities that claim something, starting from the claim's field values rather than from an identity. Answers "who claims this (e.g. this platform channel, this occupation), verified by a trusted party?" — the inverse of the identity-keyed queries above. Works for any claim type.
Optional type scope: restrict to claims of exactly this schema, by the schema's content digest. Unset (or empty value) = any schema. This is the schema's content-addressed identifier; it only groups cross-client when claimants pin identical canonical schema bytes.
Field key/value pairs a claim's (STRING) fields must contain, matched by JSONB containment. A claim matches only when it contains every supplied pair (AND); it may carry additional fields. A claim missing any supplied field does not match. May be empty when schema_digest scopes the query.
Only return claims that carry a VerificationVerify authored by one of these identities (the trust roots). Required and non-empty — this is what makes a match "verified" rather than merely "claimed".
ResolveVerifiedClaimsResponse
Matching claims, each wrapped with its targets and verifies (the verifies include at least one authored by a trusted identity).
Additional events that may be helpful, like relevant identity and profiles
verifications.proto
VerificationSchemaSchema that defines the verification These are self describing schemas and are intended to be specified in a `VerificationClaim`.
Schema that defines the verification These are self describing schemas and are intended to be specified in a VerificationClaim.
Human readable name of the schema (ie. X Verification).
FieldDef
Key used in VerificationClaim.fields, e.g. "handle", "proof_url".
How to decode this field's bytes.
Semantic refinement of kind: "url", "email", "iso8601-date", "hex". Free-form so new formats need no proto change.
SerializedVerificationSchemaProtobuf serialization is non-deteministic.
Protobuf serialization is non-deteministic. We hash the serialized schema so we have the canonical hash - this aids with grouping of claims.
Serialized VerificationSchema.
Digest over schema_bytes. Verify digest == hash(schema_bytes).
VerificationClaimClaim a user makes
Claim a user makes
The schema this claim instantiates, carried inline.
Values keyed by FieldDef.key, decoded per the schema's FieldKind.
VerificationTargetTargets a claim at one or more identities.
Targets a claim at one or more identities. Separate from the claim so targeting can be set (or changed) after the claim is created.
The claim event being targeted.
Identities the claim is intended for.
VerificationVerify── A verification of a claim ──
── A verification of a claim ──
The claim event being verified. The event's author is the verifier.
FieldKindenumCanonical byte encoding per kind (claims are hashed, so reject non-canonical): STRING -> UTF-8 INT -> int64 little-endian, 8 bytes BOOL -> 0x00 / 0x01 BYTES -> verbatim
Canonical byte encoding per kind (claims are hashed, so reject non-canonical):
STRING -> UTF-8 INT -> int64 little-endian, 8 bytes BOOL -> 0x00 / 0x01 BYTES -> verbatim
Synchronises events from a client to the server