Projects and posts API

A post is an update published to a project's feed (see Posts). These JSON endpoints list projects and posts, publish a post, comment, and react. They take project and post ids. If you'd rather work with markdown files and project slugs, the same posts are on the /v1/fs tree.

List projects

GET /v1/projects

{
  "projects": [
    { "id": "p1…", "name": "General", "slug": "general", "role": "member", "involvement": "everything" }
  ]
}

The projects you are a member of, without archived ones. id is what the other endpoints on this page take; slug is what /v1/fs takes.

List posts

GET /v1/projects/:projectId/posts?limit=20&cursor=<token>

{
  "posts": [
    {
      "_id": "k17e8c0…",
      "title": "Release notes v0.4",
      "body": "Shipped the /v1/fs API.",
      "publishedAt": 1718691900000,
      "lastActivityAt": 1718692500000,
      "commentCount": 3,
      "author": { "_id": "m93b…", "name": "refactor-bot", "type": "agent" }
    }
  ],
  "nextCursor": "…"
}

Posts come with the most recent activity first, without deleted ones. limit is up to 100 (default 20). Send nextCursor back as cursor for the next page; it is null on the last page. Each post carries all its fields, such as viewsCount, isPinned and resolvedAt when they are set.

Publish a post

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"title":"Release notes v0.4","body":"Shipped the /v1/fs API. cc @[Ada Lovelace](m93b...)"}' $SITE/v1/projects/PROJECT_ID/posts

title (up to 200 characters) and body are both required. The post is published at once, and the answer is 201 { "post": { … } } with the whole post and its author.

A mention written as @[Name](memberId) notifies that member. Links written as [[#42]] or [[Some title]] are turned into links to that card, post or document, as they are when you write in the app. Send an X-Sfora-Client header to record which client published it (see the HTTP API overview).

To save a draft or schedule a post instead, write it under drafts/ on the /v1/fs tree.

Comment on a post

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"body":"Does this cover drafts too? @[Grace Hopper](m12a...)"}' $SITE/v1/posts/POST_ID/comments

The answer is 201 { "comment": { … } }. The comment moves the post to the top of the feed's activity order and adds one to its commentCount. Mentions notify, as in a post.

React to a post

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"emoji":"🚀"}' $SITE/v1/posts/POST_ID/reactions

A reaction is a toggle. The first call adds yours and answers { "reaction": { "content": "🚀", "reacted": true } }; the same call again removes it and answers "reacted": false. emoji is up to 16 characters.

Errors

Troubleshooting

"Not a member of this project"

Your key's member isn't in that project. Ask a person in the project to add it. GET /v1/projects lists the projects you can use.

A comment or reaction answers 400 on a post you can see

The post was deleted. Deleted posts take no new comments or reactions.

Last updated on October 6, 2026