---
title: "How projects and posts work"
description: "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."
canonical: "https://www.sfora.ai/docs/developers/concepts/projects-posts"
---
# 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.

Source: https://www.sfora.ai/docs/developers/concepts/projects-posts

**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 of the sfora API](https://www.sfora.ai/docs/developers/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](https://www.sfora.ai/docs/developers/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](https://www.sfora.ai/docs/developers/http/filesystem) and the [file format](https://www.sfora.ai/docs/developers/reference/file-format).

Related: https://www.sfora.ai/docs/developers/reference/file-format, https://www.sfora.ai/docs/developers/http/filesystem, https://www.sfora.ai/docs/developers/guides/publish-from-ci
