Skip to main content

Update post

PATCH 
/posts/:id

Update a scheduled or draft post. You can change content, schedule, target accounts, or media. Published posts cannot be modified — attempting to update one returns 409 conflict.

All fields in the request body are optional — send only the fields you want to change. Fields you omit are left untouched.

Round-trip safe

Every field name in this request body also appears in the response (and in GET /v1/posts/{post_id}) with the same meaning. You can pull a post down, mutate a field locally, and PATCH the same payload straight back — no field renaming required.

Don't confuse scheduled_for with created_at
  • scheduled_for is a future timestamp — when the post will publish. You set this in the request.
  • created_at is a past timestamp — when the post record was created. Response-only; you cannot change it.

Pre-2026-04-12 integrations sent this field as scheduled_at. That was a misnomer. scheduled_at is still accepted as a deprecated alias, but new integrations should always use scheduled_for.

Don't confuse media_ids (request) with media (response)
  • Request: media_ids is an array of UUID strings — ["a1b2-...", "c3d4-..."]. Sending media_ids replaces the post's media set entirely.
  • Response: media is an array of full media objects (url, type, dimensions); media_ids is a convenience array of just the UUIDs.

If you send media, media_id, mediaId, or attachments in a request body, the API returns 400 invalid_field_name with a "did you mean media_ids?" hint.

Path Parameters​

ParameterTypeRequiredDescription
post_idstring (UUID)YesUUID of the post to update. Accepts id as a deprecated alias in the URL path for back-compat.

Request Body Schema​

PATCH /posts/{post_id} — Content-Type: application/json

FieldTypeRequiredDescription
contentstringNoReplace the post's text content.
account_idsinteger[]NoReplace the set of target accounts. Accounts already published to cannot be removed.
scheduled_forstring (ISO 8601)NoReschedule to a new UTC datetime, e.g. "2026-04-20T09:00:00Z". Always send UTC. Only valid for posts still in scheduled or draft status.
timezonestringNoIANA timezone string (e.g. "America/New_York"). Display metadata only — does not affect when the post fires.
media_idsstring[] (UUID)NoReplace the attached media set. Send [] to remove all media.
platform_contentobjectNoReplace per-platform overrides (see Create Post docs for the full shape).
statusstringNoSet to "draft" to unschedule, or "scheduled" to re-queue a draft.
scheduled_atstring (ISO 8601)NoDeprecated alias for scheduled_for. Still accepted, but new integrations should use scheduled_for.

Request Example​

{
  "content": "Updated caption — new launch date confirmed!",
  "scheduled_for": "2026-04-20T09:00:00Z",
  "timezone": "UTC",
  "media_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
}

Response Examples​

200 — Post updated​

The response shape is identical to POST /v1/posts and GET /v1/posts/{post_id}. Every top-level field you sent is echoed back, plus the rich destinations[] array with per-account state.

{
  "data": {
    "post_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "scheduled",
    "content": "Updated caption — new launch date confirmed!",
    "account_ids": [2280, 2282, 2285],
    "scheduled_for": "2026-04-20T09:00:00.000Z",
    "timezone": "UTC",
    "media_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "media": [
      {
        "media_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "type": "image",
        "width": 1920,
        "height": 1080
      }
    ],
    "platform_content": {},
    "destinations": [
      {
        "account_id": 2280,
        "account_name": "@mybrand",
        "platform": "instagram",
        "status": "queued",
        "platform_post_id": null,
        "platform_post_url": null,
        "published_at": null,
        "error": null,
        "attempts": 0
      }
    ],
    "created_at": "2026-04-10T12:00:00.000Z",
    "updated_at": "2026-04-12T08:30:00.000Z",
    "next_step": "Post rescheduled to 2026-04-20T09:00:00.000Z. Call GET /v1/posts/f47ac10b-58cc-4372-a567-0e02b2c3d479 to check status."
  },
  "error": null,
  "meta": {
    "request_id": "a1b2c3d4",
    "timestamp": "2026-04-12T08:30:00.000Z"
  }
}

404 — Post not found​

{
  "data": null,
  "error": {
    "message": "Post not found.",
    "code": "not_found"
  },
  "meta": {
    "request_id": "e5f6g7h8",
    "timestamp": "2026-04-12T08:30:00.000Z"
  }
}

409 — Cannot update a published post​

{
  "data": null,
  "error": {
    "message": "Cannot update a post that has already been published.",
    "code": "post_already_published"
  },
  "meta": {
    "request_id": "i9j0k1l2",
    "timestamp": "2026-04-12T08:30:00.000Z"
  }
}

Request​

Responses​

Updated post