Skip to main content

Core Concepts

Data Model​

PostBoost is multi-tenant. Every resource lives inside a Workspace.

User
└── Workspace (many-to-many via role)
├── Account (connected social profile: Twitter, Instagram, …)
├── Post (scheduled or published content)
├── Media (uploaded images / videos)
└── Tag (color-coded labels for posts)

User​

A person with login credentials. A user can belong to multiple workspaces with different roles (Owner, Admin, Member).

Workspace​

The top-level container for all your social media activity. Every API call that touches posts, accounts, media, or tags requires a workspaceUuid. Get yours from the dashboard URL or via GET /panel/workspaces (admin) or GET /workspaces.

Account​

A connected social media profile — for example, a Twitter account or an Instagram business profile. Accounts belong to a Workspace. When creating a post you specify which Account IDs to publish to.

Post​

A piece of content to be published. Posts have one or more versions — one version per target Account — letting you customize copy per platform. One version must be marked is_original: true.

Each version carries an ordered content array. Item 0 is the post itself. A second item means different things per network:

NetworkSecond content item
Facebook Page, Instagram, LinkedInPublished as the first comment under the post (one comment only; Facebook Stories take none)
X, Threads, Bluesky, Mastodon, PixelfedPublished as the next post of a thread; add more items for longer threads
YouTube, TikTok, Pinterest, Google Business ProfileIgnored
"content": [
{ "body": "Our API 1.8 is live.", "media": [345] },
{ "body": "Full changelog: https://postboost.co/docs/changelog/" }
]

The first comment is posted right after the post goes live. If it fails, the post stays published and the account's entry on the post carries the error. First comments on Facebook Pages and Instagram depend on Meta's app review; see Network permissions status.

Media​

Uploaded image or video files that can be attached to post versions. See Media Uploads for upload flows.


API Tiers​

PostBoost has two distinct groups of endpoints:

Workspace-scoped endpoints​

GET /{workspaceUuid}/accounts
GET /{workspaceUuid}/posts
POST /{workspaceUuid}/posts
GET /{workspaceUuid}/media
GET /{workspaceUuid}/tags

Used for day-to-day operations within a single workspace. Any valid API token with access to that workspace can call these. Most integrations only ever use these endpoints.

Admin (panel) endpoints​

GET /panel/workspaces
GET /panel/users
GET /panel/subscriptions
GET /panel/receipts

Used for platform administration — managing workspaces, users, billing, and subscriptions. Requires an admin-role token. Non-admin tokens receive 403 Forbidden.

info

If you only need to publish posts and manage social accounts, you will never need /panel/* endpoints.


Brand voice​

Each workspace can hold one brand voice: who the brand is, its audience, three tone sliders (formal, playful, technical), emoji and hashtag habits, words to avoid, preferred calls to action and up to five example posts. It is the same profile as the Brand Voice page in the app. Read and change it with GET / PUT /{workspaceUuid}/brand-voice.

The AI endpoints use it without being asked: blog-to-social writes captions in that voice, and image-prompt / image-generate derive a short visual tone from it. image-edit applies it only with use_brand_voice: true; image-variations and image-alt-text never do (alt text must describe the image literally). Send use_brand_voice: false to skip it on one call. Each response says whether it was used in meta.brand_voice_applied.


Templates, hashtag groups, account groups and queue times​

Everything on these pages of the app is also in the API:

  • Templates (/templates): reusable post content. Read one and send its content as a post version.
  • Hashtag groups (/hashtag-groups): saved hashtag sets to append to a post body.
  • Account groups (/account-groups): named sets of accounts. Send a group's account_ids as accounts when you create a post.
  • Posting schedule (/posting-schedule): the queue's times per weekday, for the workspace (account_id 0) or one account. Posts added to the queue take the next free time; GET /queue/slots shows what is coming up and GET /posting-schedule/recommended suggests times from past engagement. Changing it needs a workspace admin.
  • Competitors (/competitors): public Instagram accounts tracked from one of your Instagram accounts. Adding one returns 202 and imports its numbers in the background.

Finding Your Workspace UUID​

curl https://postboost.co/app/api/workspaces \
-H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
"data": [
{ "uuid": "ws-abc123", "name": "Acme Co" }
]
}

Use ws-abc123 as {workspaceUuid} in all subsequent workspace-scoped requests.


Next steps​