Posts

Create, update, and manage project updates and posts programmatically.

Endpoints

List posts in your workspace

Scope

posts:read

Parameters

projectIdstringFilter by project (query param)

statusstringFilter by status: draft or published (default: published)

limitnumberNumber of posts (max 100, default 50)

cursorstringCursor for pagination (from nextCursor in previous response)

Response

{
  "posts": [
    {
      "id": "pst_abc123",
      "postNumber": 12,
      "identifier": "WR-12",
      "sequenceNumber": 12,
      "title": "Weekly Update",
      "status": "published",
      "author": {
        "id": "usr_def456",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "image": "/api/media/avatars/jane.jpg"
      },
      "createdAt": "2024-02-01T12:00:00Z",
      "updatedAt": "2024-02-01T14:30:00Z",
      "publishedAt": "2024-02-01T14:30:00Z"
    }
  ],
  "hasMore": true,
  "nextCursor": 1706797800000
}

Create a new post

Scope

posts:write

Parameters

titlestringrequiredPost title (max 200 chars)

contentstring|objectrequiredPost content (plain text or JSON). Max 10,000 characters of plain text.

projectIdstringrequiredProject ID to post in

statusstringdraft or published (default: draft)

Get a single post by ID

Scope

posts:read

Parameters

idstringrequiredPost ID (URL path)

Update an existing post

Scope

posts:write

Parameters

idstringrequiredPost ID (URL path)

titlestringNew title

contentstring|objectNew content (plain text or JSON). Max 10,000 characters of plain text; legacy oversize posts may be saved only while strictly reducing length.

statusstringdraft or published

projectIdstringMove post to a different project (must be in same organization)

Delete a post (soft delete)

Scope

posts:write

Parameters

idstringrequiredPost ID (URL path)

Content Format

The content field accepts either plain text (string) or a structured JSON object representing rich text content. When using the rich text format, content follows the Plate.js JSON schema.

Plain-text length is capped at 10,000 characters. Requests over the limit return HTTP 400 with a message of the form Post content exceeds 10,000 character limit. For JSON content, the limit applies to the extracted plain text (inline text concatenated, blocks joined with newlines).

Pagination

The list posts endpoint uses cursor-based pagination. Pass the nextCursor value from the previous response as the cursor query parameter to fetch the next page. The response includes a hasMore flag to indicate if more results are available.

The cursor is the last returned post's createdAt timestamp. Post lists always respect the key owner's current workspace and project visibility, so hidden private-project posts are skipped instead of being exposed through pagination.

Post Status

draftOnly visible to the author. Default status for new posts.

publishedVisible to all project members. Triggers notifications.