Posts API

The /v1/posts endpoints let you create, list, and delete posts. Creating a post is the core operation — it's how you cross-post, schedule, and attach media programmatically.

All endpoints require authentication.

---

Create a post

POST /api/v1/posts

Creates a post. Depending on the body, it becomes a draft (no scheduledAt) or a scheduled post. A single call can fan out to multiple accounts (cross-post) with per-channel overrides.

Request body

Field	Type	Required	Description
accountIds	string[]	yes	One or more connected account IDs to post to. Min 1.
caption	string	no	The default caption text.
firstComment	string	no	A comment to post immediately after publish.
postType	string	no	Post type (e.g. post, reel, story, short, thread). Defaults to post.
mediaIds	string[]	no	Media asset IDs to attach (must be owned by you).
accountOverrides	array	no	Per-channel caption/field overrides (see below).
threadParts	Record of accountId → string[]	no	Thread renditions (postType thread). Chain platforms carry N parts; LinkedIn/Facebook carry the full text as one element. null clears.
scheduledAt	string (ISO 8601)	no	Omit to save as a draft; include to schedule.

accountOverrides[]

Field	Type	Description
accountId	string	The account this override applies to.
captionOverride	string | null	Replace the caption for this channel.
fields	object	Platform-specific field overrides ({ key: value }).

Validation

Before any rows are written, the request is validated against platform limits: caption length, post type, media constraints (count, size, aspect ratio, duration), and ownership of both accountIds and mediaIds.

• A constraint violation returns 400 with a clear message.
• A foreign-id ownership failure (account/media not owned by you) returns 403.

Example: cross-post with overrides

curl -X POST https://<your-api-origin>/api/v1/posts \
  -H "Authorization: Bearer gx_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Our new feature ships today 🚀",
    "postType": "post",
    "accountIds": ["acc_instagram", "acc_x", "acc_linkedin"],
    "mediaIds": ["med_01"],
    "accountOverrides": [
      { "accountId": "acc_x", "captionOverride": "New feature, shipping today." },
      { "accountId": "acc_linkedin", "captionOverride": "Today we are launching..." }
    ],
    "scheduledAt": "2026-07-15T14:30:00Z"
  }'

Example: draft (no schedule)

curl -X POST https://<your-api-origin>/api/v1/posts \
  -H "Authorization: Bearer gx_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Draft caption",
    "accountIds": ["acc_instagram"]
  }'

Response — 201 Created

{
  "id": "pst_abc123",
  "status": "scheduled"
}

status is "scheduled" when scheduledAt is provided, otherwise "draft".

Errors

Status	Meaning
400	Invalid request body, or platform-limit violation
403	accountIds or mediaIds not owned by you
401	Missing/invalid API key
500	Post creation failed unexpectedly

---

List posts

GET /api/v1/posts

Returns your posts, newest first. Uses standard pagination.

Query parameters

Parameter	Type	Default	Range
limit	integer	25	1–100
offset	integer	0	≥ 0

Example

curl "https://<your-api-origin>/api/v1/posts?limit=10&offset=0" \
  -H "Authorization: Bearer gx_live_YOUR_API_KEY"

Response — 200 OK

{
  "data": [
    {
      "id": "pst_abc123",
      "userId": "usr_...",
      "caption": "Our new feature ships today 🚀",
      "firstComment": null,
      "postType": "post",
      "status": "scheduled",
      "scheduledAt": "2026-07-15T14:30:00.000Z",
      "createdAt": "2026-07-12T09:00:00.000Z",
      "updatedAt": "2026-07-12T09:00:00.000Z"
    }
  ],
  "limit": 10,
  "offset": 0
}

Only posts owned by the authenticated user are returned.

---

Delete a post

DELETE /api/v1/posts/:id

Deletes a post. Only drafts and scheduled posts can be deleted — published posts cannot be deleted via the API (they return 400).

Example

curl -X DELETE https://<your-api-origin>/api/v1/posts/pst_abc123 \
  -H "Authorization: Bearer gx_live_YOUR_API_KEY"

Response — 200 OK

{ "success": true }

Errors

Status	Meaning
400	Cannot delete published post
404	Post not found (or not owned by you)
401	Missing/invalid API key

note

This deletes the post in post.buzz. It does not delete the post from the social platform itself. Whether a published post can be removed from a platform depends on that platform's capabilities — see the capability matrix.