List Posts

GET/api/posts

Returns a paginated list of posts for the authenticated user.

Query parameters

statusstringquery

Filter by status. One of: pending, queued, publishing, published, failed, rejected, cancelled. Omit to return all non-archived posts.

pagenumberquerydefault: 1

Page number (1-indexed). Page size is fixed at 20.

Response fields

postsarray

Array of post objects.

totalnumber

Total number of posts matching the filter.

totalPagesnumber

Total pages available.

{
  "posts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "platform": "twitter",
      "content_text": "Just launched our new API...",
      "status": "queued",
      "scheduled_at": "2026-05-22T10:00:00+00:00",
      "published_at": null,
      "source": "manual",
      "platform_post_url": null,
      "media_urls": [],
      "created_at": "2026-05-21T08:00:00+00:00",
      "error_message": null,
      "connected_accounts": {
        "display_name": "@yourhandle",
        "avatar_url": "https://..."
      }
    }
  ],
  "total": 42,
  "page": 1,
  "pageSize": 20,
  "totalPages": 3
}

Delete / Cancel Post

DELETE/api/posts

Cancels a pending or queued post. Posts with status publishing, published, or failed cannot be cancelled.

Request body

postIdstringbodyrequired

UUID of the post to cancel.

Response fields

okboolean

true when the post was cancelled.

{ "ok": true }

Edit Post

PATCH/api/posts/:id

Edits the content, schedule time, or first comment of a post in pending, queued, or draft status. At least one field must be provided.

Path parameters

idstringpathrequired

UUID of the post to edit.

Request body

contentTextstringbody

New post content. Min 1 character.

scheduledAtstringbody

New ISO 8601 datetime with timezone offset (e.g., 2026-05-22T14:30:00+05:30).

firstCommentstring | nullbody

First comment to post immediately after publishing. Pass null to remove.

Response fields

postobject

The updated post object.

{
  "post": {
    "id": "550e8400-...",
    "content_text": "Updated post content",
    "scheduled_at": "2026-05-22T14:30:00+00:00",
    "status": "queued"
  }
}

Cancel Post by ID

DELETE/api/posts/:id

Cancels a single post by ID. Only pending and queued posts can be cancelled.

Path parameters

idstringpathrequired

UUID of the post to cancel.

Response fields

okboolean

true when the post was cancelled.

{ "ok": true }

Error Responses

Status	Error
`400`	Post cannot be cancelled (wrong status)
`404`	Post not found
`429`	Rate limit exceeded (20 write requests/minute)