# Posts and editorial workflow

Use these protected routes to create, revise, preview, publish, schedule, and
retire posts in one publication. New posts begin as drafts; lifecycle changes
use dedicated actions rather than setting `status` through `/post/save`.

## Authentication

Every route requires a bearer token, the listed capability, and the effective
workspace principal's active publication membership. Organization workspaces
also apply their current verified Management grants. All routes accept an
existing `post_id`. Where a post ID is not provided, use `publication_id` or
`publication_slug` with `slug`.

## Routes

| Route | Methods | Capability | Required input | Optional input and behavior | Success result |
| --- | --- | --- | --- | --- | --- |
| `/post/list` | `GET`, `POST` | `post.list` | Publication selector | `category_id`, `status`, `visibility`, `archived`, pagination | Paginated `posts`. |
| `/post/get` | `POST` | `post.list` | Post selector | Publication selector must match when supplied. | `post`. |
| `/post/save` | `POST` | `post.save` | Create: publication selector, `title`; update: `post_id` | `slug`, `excerpt`, `featured_media_id`, `category_id`, `body`, `body_format`, `visibility`, `tag_ids`, `author_ids` | Saved `post`. |
| `/post/preview` | `POST` | `post.preview` | `post_id` | — | Rendered `preview`. |
| `/post/submit-review` | `POST` | `post.submit_review` | Post selector | — | Review post. |
| `/post/schedule` | `POST` | `post.schedule` | Post selector, `scheduled_at` | — | Scheduled post. |
| `/post/cancel-schedule` | `POST` | `post.cancel_schedule` | Post selector | — | Draft post. |
| `/post/publish` | `POST` | `post.publish` | Post selector | — | Published post. |
| `/post/unpublish` | `POST` | `post.unpublish` | Post selector | — | Draft post. |
| `/post/archive` | `POST` | `post.archive` | Post selector | — | Archived post. |
| `/post/restore` | `POST` | `post.restore` | Post selector | — | Restored post. |
| `/post/delete` | `POST` | `post.delete` | Post selector | — | Deleted `post_id`. |

## Save a post

### Request fields

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| `post_id` | No | UUID | Updates this post. Omit to create. |
| `publication_id` / `publication_slug` | Required on create | UUID / String | Selects the publication. Optional on update only as a matching assertion. |
| `title` | Required on create | String | Post title. |
| `slug` | No | String | Unique within the publication. Omit or send an empty value to derive it from `title`. |
| `excerpt` | No | String or `null` | Summary text; an empty value clears it. |
| `featured_media_id` | No | UUID or `null` | Ready media from this publication; `null` or an empty value clears it. |
| `category_id` | No | UUID or `null` | One category from this publication; `null` or an empty value clears it. |
| `body` | No on update; required before publication | String | Source content. |
| `body_format` | No | `markdown` or `html` | Defaults to `markdown` for a new post. |
| `visibility` | No | `public`, `unlisted`, or `private` | Defaults to `public` for a new post. |
| `tag_ids` | No | UUID array | Replaces all tag assignments when supplied. |
| `author_ids` | No | UUID array | Replaces all author assignments when supplied. |

```bash
curl -sS https://api.blog.service.m7.org/v1/post/save \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "publication_slug":"engineering-notes",
    "title":"Release notes",
    "body":"# Release notes",
    "body_format":"markdown",
    "visibility":"public",
    "tag_ids":["TAG_UUID"],
    "author_ids":["AUTHOR_UUID"]
  }'
```

```json
{
  "status": 1,
  "comment": "post saved",
  "data": {
    "saved": true,
    "post": {
      "post_id": "POST_UUID",
      "publication_id": "PUBLICATION_UUID",
      "slug": "release-notes",
      "title": "Release notes",
      "status": "draft",
      "visibility": "public",
      "archived": 0
    }
  }
}
```

`/post/list` defaults to `archived: 0`. The `status` filter accepts `draft`,
`review`, `scheduled`, and `published`; the `visibility` filter accepts
`public`, `unlisted`, and `private`. If a `category_id` is supplied, it must
belong to the selected publication.

## Preview

`/post/preview` renders the stored post; it does not accept unsaved content.
It requires `post_id` and returns `preview.body` as HTML, with
`source_body_format` showing whether the stored source is Markdown or HTML.

## Lifecycle

| Action | Allowed current state | Next state | Notes |
| --- | --- | --- | --- |
| `/post/submit-review` | `draft` | `review` | Archived posts cannot transition. |
| `/post/schedule` | `draft` or `review` | `scheduled` | `scheduled_at` must be a future timestamp. |
| `/post/cancel-schedule` | `scheduled` | `draft` | Clears `scheduled_at`. |
| `/post/publish` | Eligible open post | `published` | Requires title, slug, body, and valid `body_format`; clears `scheduled_at`. |
| `/post/unpublish` | `published` | `draft` | Clears `scheduled_at`. |
| `/post/archive` | Any open post | Same editorial status, archived | Preserves editorial state. |
| `/post/restore` | Archived post | Same editorial status, open | Preserves editorial state. |

Send a post selector to each action, for example:

```json
{ "post_id": "POST_UUID", "scheduled_at": "2026-09-01T09:00:00Z" }
```

Scheduling records the requested time but does not automatically publish the
post. A post must be archived before `/post/delete`; otherwise it returns
`409`. Successful deletion also removes the post's author and tag assignments.

## Public availability

Public list and archive routes show only posts that are `published`,
`public`, and unarchived. Direct public post reads also allow `unlisted`
posts. `private`, draft, review, scheduled, and archived posts are not exposed
by the public read API.
