Skip to main content
A post is a planned publication. It carries text, optional media, and per-network settings, targets exactly one profile, and moves through a predictable lifecycle from creation to publication. If you need to publish the same content to several profiles, create one post per profile.

​
Lifecycle

The response field friendly_status is the user-facing label (e.g. “Scheduled for Dec 25” instead of the raw waiting).

​
Publish types

The publish_type field controls when a post goes live: The dashboard refers to these as Post now, Schedule, and Add to queue respectively.

​
Queues and timeslots

Each profile has a configurable queue — a recurring weekly schedule of timeslots (e.g. “Tue 9am, Thu 2pm, Sat 11am”). Posts created with publish_type: queue_using_timeslots get assigned to the next available slot automatically. Slots are managed in the dashboard’s queue editor.

​
Media

Posts can carry one or more media files. Attach them by setting media_content_ids to an array of IDs from the media library. Each network has its own rules:
  • X — up to 4 images, or 1 video.
  • Instagram feed — 1 image/video, or up to 10 in a carousel.
  • Instagram Reels — exactly 1 video.
  • TikTok / YouTube Shorts — exactly 1 video.
  • Facebook / LinkedIn — varies by network.
The API validates these constraints when you create a post and returns a 422 with a descriptive message if the combination is invalid.

​
Per-network parameters

The PostResource schema includes nullable fields for parameters specific to a single network. Only set them when targeting that network:
Refer to POST /workspaces/{workspace}/posts in the API reference for the canonical request shape.

​
Reading a published post’s URL

Once status becomes published, the url field contains the canonical URL on the social network. The related social_post object holds network-specific identifiers (e.g. Instagram media ID, X tweet ID) that you can use to fetch metrics or reply.

​
Editing posts

You can update a post while it’s still in draft, needs_approval, or waiting. Once it transitions to publishing or beyond, edits are rejected — at that point, the content is in the social network’s hands. Use PUT /posts/{post} to update, or DELETE /posts/{post} to cancel a scheduled post before it publishes.

​
Comments and notes

Posts support two collaboration features:
  • Comments — discussion threads visible inside the dashboard for the team to review content before it publishes. They are returned on PostResource.comments.
  • Notes — short labels (think Post-it sticky notes) attached to a post. Returned on PostResource.notes.
Both are workspace-internal — they’re never sent to the social network.

​
Next

Schedule posts

A walkthrough of all three publish types.

Media library

Uploading and organising assets that posts can use.