Skip to content

API.md

Latest commit

 

History

History
319 lines (230 loc) · 5.81 KB

API.md

File metadata and controls

319 lines (230 loc) · 5.81 KB

Private Posts API

This document outlines the required XRPC endpoints for the private posts service. All endpoints will be implemented using the AT Protocol's XRPC server and lexicons.

Endpoint Overview

Each line represents a required XRPC endpoint with its purpose:

# Trust Management (Graph)
social.spkeasy.graph.getTrusted               - List users trusted by the given author DID
social.spkeasy.graph.addTrusted               - Add a new trusted user
social.spkeasy.graph.removeTrusted            - Remove a trusted user

# Session Management
social.spkeasy.privateSession.revoke          - Revoke an active session
social.spkeasy.privateSession.addUser         - Add new trusted user to the current session
social.spkeasy.privateSession.getSession      - Get the currecnt active session

# Post Management
social.spkeasy.privatePosts.getPosts          - List private posts accessible to a recipient
social.spkeasy.privatePosts.createPost        - Create a new private post
social.spkeasy.privatePosts.deletePost        - Delete a private post

social.spkeasy.reaction.createReaction        - Create like
social.spkeasy.reaction.deleteReaction        - Delete like

social.spkeasy.notification.getUnreadCount    - Get count of unread notifications
social.spkeasy.notification.listNotification  - List notifications
social.spkeasy.notification.updateSeen        - Update last seen time for notifications

# User management
social.spkeasy.actor.getProfile               - Returns encrypted private profile
social.spkeasy.actor.putProfile               - Update encrypted private profile

# Feature Management
social.spkeasy.actor.getFeatures              - Get features enabled for an actor
social.spkeasy.actor.applyInviteCode          - Apply a code to enable a feature

# Key Management                              - Swiss service
social.spkeasy.keys.getPublicKey              - Get user's public key for encryption
social.spkeasy.keys.getPrivateKey             - Get user's private key (owner only)
social.spkeasy.keys.rotate                    - Request key rotation

# Misc.
social.spkeasy.actor.donate                   - Donate to Speakeasy as a single payment or monthly subscription

Trust Management

Get Users Who Trust a DID

GET / xrpc / social.spkeasy.graph.getTrusts;

Returns a list of users who trust the specified DID.

Parameters:

  • did (required): The DID to check for trust relationships

Response:

{
  "trustedBy": Array<{
    did: string
    createdAt: string
  }>
}

Add Trusted User

POST / xrpc / social.spkeasy.graph.addTrusted;

Adds a new user to the trusted followers list.

Request Body:

{
  "did": string  // DID of the user to trust
}

Response:

{
  "success": boolean
}

Remove Trusted User

POST / xrpc / social.spkeasy.graph.removeTrusted;

Removes a user from the trusted followers list.

Request Body:

{
  "did": string  // DID of the user to remove
}

Response:

{
  "success": boolean
}

Session Management

Revoke Session

POST / xrpc / social.spkeasy.privateSession.revoke;

Revokes an active session, forcing creation of a new session for future posts.

Request Body:

{
  "sessionId": string
}

Response:

{
  "success": boolean
}

Add User to Session

POST / xrpc / social.spkeasy.privateSession.addUser;

Adds a new trusted user to an existing session.

Request Body:

{
  "sessionId": string
  "did": string
}

Response:

{
  "success": boolean
}

Post Management

Fetch Posts for a Recipient

GET / xrpc / social.spkeasy.privatePosts.getPosts;

Returns a list of private posts that the specified recipient has access to.

Parameters:

  • recipient (required): The DID of the recipient
  • limit (optional): Number of posts to return (default: 50)
  • cursor (optional): Pagination cursor
  • uris (optional): Array of specific post URIs to fetch

Response:

{
  "posts": Array<{
    uri: string
    rkey: string
    author: {
      did: string
      handle: string
    }
    text: string
    createdAt: string
    sessionId: string
  }>,
  "cursor": string
}

Create Post

POST / xrpc / social.spkeasy.privatePosts.createPost;

Creates a new private post in the specified session.

Request Body:

{
  "sessionId": string
  "text": string
  "recipients": string[]  // Array of recipient DIDs
}

Response:

{
  "uri": string
  "rkey": string
  "author": {
    "did": string
    "handle": string
  }
  "text": string
  "createdAt": string
  "sessionId": string
}

Delete Post

POST / xrpc / social.spkeasy.privatePosts.deletePost;

Deletes a private post. Only the author can delete their own posts.

Request Body:

{
  "uri": string  // The URI of the post to delete
}

Response:

{
  "success": boolean
}

Key Management

Get Public Key

GET / xrpc / social.spkeasy.keys.getPublicKey;

Returns a user's public key for encryption.

Parameters:

  • did (required): The DID of the user whose public key to fetch

Response:

{
  "publicKey": string  // Base64 encoded public key
}

Get Private Key

GET / xrpc / social.spkeasy.keys.getPrivateKey;

Returns the authenticated user's private key. Only accessible to the key owner.

Response:

{
  "privateKey": string  // Base64 encoded private key
}

Rotate Keys

POST / xrpc / social.spkeasy.keys.rotate;

Requests rotation of the user's key pair.

Response:

{
  "success": boolean
}