Posts API

List Posts

GET /api/v1/posts

Query Parameters:

Parameter	Type	Default	Description
`status`	string	—	Filter by status: `draft`, `scheduled`, `published`, `partially_published`
`limit`	integer	50	Max results (1–100)
`offset`	integer	0	Pagination offset

Response:

{
  "data": [
    {
      "id": "uuid",
      "originalIdea": "...",
      "linkedInBody": "...",
      "xBody": "...",
      "circleBody": "...",
      "instagramBody": "...",
      "status": "draft",
      "contentMode": "short_form",
      "tags": [],
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "limit": 50,
    "offset": 0
  }
}

Create a Post

POST /api/v1/posts

Request Body:

{
  "originalIdea": "Your raw brain dump here",
  "linkedInBody": "Optional pre-formatted LinkedIn copy",
  "xBody": "Optional tweet text",
  "circleBody": "Optional Circle post body",
  "circleTitle": "Optional Circle post title",
  "instagramBody": "Optional Instagram caption",
  "contentMode": "short_form",
  "tagIds": ["uuid-1", "uuid-2"]
}

Only originalIdea is required for short-form posts. All platform body fields are optional — you can set them later via update or by using the reformat flow in the UI.

Response: 201 with the created post in data.

Get a Post

GET /api/v1/posts/:id

Returns the full post object including all platform bodies, image URLs, scheduling info, tags, and long-form stage data.

Update a Post

PATCH /api/v1/posts/:id

Send only the fields you want to update. All fields are optional.

Updatable fields include:

originalIdea, linkedInBody, xBody, circleBody, circleTitle, instagramBody
linkedInImageUrl, xImageUrl, circleImageUrl, instagramImageUrl
status
scheduledAt, linkedInScheduledAt, xScheduledAt, circleScheduledAt, instagramScheduledAt
scheduledPlatforms
tagIds
Long-form fields: selectedTitle, selectedOutline, selectedScript, selectedHook, longformStage

Delete a Post

DELETE /api/v1/posts/:id

Response:

{
  "data": {
    "id": "uuid",
    "deleted": true
  }
}

Publish a Post

POST /api/v1/posts/:id/publish

Publishes or schedules a post to selected platforms.

Request Body (all optional):

{
  "platforms": ["linkedin", "x"],
  "schedule": {
    "globalTime": "2025-02-01T09:00:00Z",
    "linkedin": "2025-02-01T09:00:00Z",
    "x": "2025-02-01T12:00:00Z"
  }
}

Omit platforms to publish to all connected platforms
Omit schedule to publish immediately
Include schedule to queue for future publication

Immediate publish response:

{
  "data": {
    "id": "uuid",
    "published": true,
    "results": {
      "linkedin": { "id": "linkedin-post-id" },
      "x": { "id": "tweet-id" }
    },
    "errors": []
  }
}

Scheduled response:

{
  "data": {
    "id": "uuid",
    "scheduled": true,
    "platforms": ["linkedin", "x"]
  }
}