Skip to main content

Posts API

The Posts namespace provides operations for creating posts, adding comments, reacting to content, and bookmarking.

See Posts concept doc for product-level details.

Key Endpoints​

Create post - POST /posts

Get post - GET /posts/{id}

Update post - PUT /posts/{postId}

Delete post - DELETE /posts/{postId}

Create comment - POST /posts/{postId}/comments

Add reaction - POST /posts/{postId}/reactions

Bookmark post - POST /posts/{postId}/bookmarks

Pin post - POST /posts/{postId}/pin (admin only)

Common Workflows​

Create a Post​

POST /posts
{
  "spaceDID": "space_abc123",
  "title": "Project Update",
  "body": "We shipped the new feature today!",
  "coverId": "media_xyz"  // optional
}

All posts belong to a space. Title is optional.

Add Media to Posts​

  1. Upload media first (see Media API):
POST /media
{
  "filename": "screenshot.png",
  "contentType": "image/png"
}

# Returns presigned upload URL and media ID
  1. Upload file to presigned URL
  2. Reference media ID in post:
POST /posts
{
  "spaceDID": "space_abc123",
  "body": "Check out this screenshot",
  "attachmentIds": ["media_xyz"]
}

Comment on a Post​

POST /posts/{postId}/comments
{
  "body": "Great work on this!"
}

Comments are direct replies to posts with body and optional attachments (no title or cover). They can be edited (15-min window), deleted, and reacted to like posts.

React to Content​

Like:

POST /posts/{postId}/reactions
{
  "reaction": "like"
}

Emoji reaction:

POST /posts/{postId}/reactions
{
  "reaction": ":tada:"
}

Use "like" for likes or emoji shortcodes (:heart:, :fire:, etc.) for emoji reactions. Idempotent - calling multiple times with the same reaction has no additional effect. To remove a reaction, use DELETE /posts/{postId}/reactions/{reaction}.

Bookmark Posts​

POST /posts/{postId}/bookmarks

Add a bookmark. To remove, use DELETE /posts/{postId}/bookmarks. Bookmarks are personal - only you see your bookmarks.

List your bookmarks:

GET /posts?onlyMyBookmarks=true

Filter posts to only those you've bookmarked across all spaces.

Edit a Post​

PUT /posts/{postId}
{
  "postId": "post_abc123",
  "title": "Updated Title",
  "body": "Updated content"
}

Edit history is preserved cryptographically. Comments have a 15-minute edit window after creation, after which they're locked.

Delete a Post​

DELETE /posts/{postId}

Soft deletion - structure remains, content is cleared. Shows as [deleted].

Pinning Posts​

Admins can pin posts to keep them at the top of the space feed.

Pin a Post​

POST /posts/post_abc123/pin

Requires admin role. Pinned posts appear first, ordered by pin date.

Unpin a Post​

DELETE /posts/post_abc123/pin

Filter by Pinned Status​

# Include pinned posts at the top (default)
GET /posts?spaceDID=space_xyz&showPinned=true

# Exclude pinned posts from results
GET /posts?spaceDID=space_xyz&showPinned=false

When showPinned=true (default), all posts are returned with pinned posts appearing first. When showPinned=false, pinned posts are excluded entirely. There is no way to fetch only pinned posts.

Authorization​

  • Creating posts: Space members
  • Viewing posts: Space members only
  • Editing posts: Original author only
  • Deleting posts: Original author only
  • Commenting: Space members
  • Reacting: Space members
  • Bookmarking: Anyone who can view the post

See Also​