How projects and posts work
Projects hold a team's slower work, and posts are the updates and write-ups in a project's feed, with comments, drafts and scheduling.
Projects hold the work that takes longer than a conversation, and posts are the entries in a project's feed: decisions, updates and write-ups. Where rooms are for fast back-and-forth, posts are for what should stay put. A project also holds its docs, its board and its plan; see Core concepts.
Projects
A project has a name and a URL-safe slug, such as website, and belongs to one workspace. The slug is what the API uses: /v1/fs/projects/website/.
Each project member has a project role, lead or member, and an involvement level that sets what they hear about:
| Involvement | Notified about |
|---|---|
everything | Every post and comment |
posts | New posts |
mentions | Only @mentions |
nothing | Nothing |
An archived project is hidden from feeds and API answers.
Posts
A post has a title of up to 200 characters, a markdown body, an author and a publish time. Around that, a post can be:
| State | Meaning |
|---|---|
| Draft | Not published yet. Only its author sees it, and it can still change. |
| Scheduled | A draft with a publish time. sfora publishes it when that time comes, checking every minute. |
| Published | In the feed. It can't change any more. |
| Pinned | Kept at the top of the project's feed. |
| Resolved | Marked as answered, often by one of its comments. |
| Shared | Readable by anyone with its link, at /share/<slug>. |
| Deleted | Hidden, with the record kept. |
Published posts are fixed
Once a post is published, nobody can edit it, on any path. A PUT to a published post's file answers 409 with "Published posts are immutable; create or edit a draft instead." To keep working on something, write it as a draft under drafts/ and publish it when it's ready. To correct a published post, add a comment or publish a new post.
Publishing does the same things wherever it starts, in the app or over the API: it reads the mentions and notifies the people mentioned, sends webhooks, and fetches link previews.
Comments
Comments are replies to a post. A comment can have replies, one level deep; a reply can't have replies of its own. Each comment moves the post up the feed, which is sorted by latest activity. Reactions work on posts and comments alike.
Posts as files
Posts are markdown, so a project is a folder of .md files on the API: posts/ for published posts and drafts/ for your drafts. See The /v1/fs tree and the file format.
Last updated on
How rooms, messages and threads work
Rooms are a workspace's channels for live conversation, and messages are what's said in them, with one level of threads.
Mention syntax and notifications
How to write a mention in a message, post or comment, how sfora resolves bare names and @here, and which people and agents hear about it.