Publish your first post

This guide assumes you’ve already followed the Quickstart — you’ve got an API token, a workspace ID, and at least one connected social profile. Here we’ll go deeper into what each step does and the options you have at each one.

1. Choose a target profile

A post targets exactly one profile. Decide where the post should land first.

curl "https://api.publishbuddy.com/v1/workspaces/$WORKSPACE_ID/profiles" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN"

Pick the relevant profile from the response (note its id and the network it belongs to — this determines what fields apply). See Social profiles for the per-network field guide.

2. Prepare media (optional)

If your post needs an image or video, upload it first. Uploads go directly to storage in three steps — presign, PUT the bytes, then confirm:

# 1. Presign
curl -X POST "https://api.publishbuddy.com/v1/workspaces/$WORKSPACE_ID/media_contents/presign" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "files": [{ "name": "photo.jpg", "mime": "image/jpeg", "size": 184293 }] }'

# 2. Upload the bytes to the returned upload_url (replaying upload_headers)
curl -X PUT "$UPLOAD_URL" -H "x-amz-acl: public-read" --data-binary @./photo.jpg

# 3. Confirm
curl -X POST "https://api.publishbuddy.com/v1/workspaces/$WORKSPACE_ID/media_contents/confirm" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "uuids": ["'"$MEDIA_ID"'"] }'

The temporary media id returned by presign is the id you’ll reference from the post. See Upload and manage media for the full flow, or reuse an existing media library file if you already have one.

For text-only posts (e.g. an X update with no image), skip this step entirely.

3. Create the post

The minimum required fields are profile_id, text (or media_content_ids), and publish_type.

curl -X POST "https://api.publishbuddy.com/v1/workspaces/$WORKSPACE_ID/posts" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "'"$PROFILE_ID"'",
    "text": "Launching today — meet our new feature.",
    "media_content_ids": ["'"$MEDIA_ID"'"],
    "publish_type": "now"
  }'

const res = await fetch(
  `https://api.publishbuddy.com/v1/workspaces/${workspaceId}/posts`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.PUBLISHBUDDY_TOKEN}`,
      'Content-Type': 'application/json',
      Accept: 'application/json',
    },
    body: JSON.stringify({
      profile_id: profileId,
      text: 'Launching today — meet our new feature.',
      media_content_ids: [mediaId],
      publish_type: 'now',
    }),
  }
);
const { data: post } = await res.json();
console.log(post.id, post.friendly_status);

import os, requests

res = requests.post(
    f'https://api.publishbuddy.com/v1/workspaces/{workspace_id}/posts',
    headers={
        'Authorization': f'Bearer {os.environ["PUBLISHBUDDY_TOKEN"]}',
        'Accept': 'application/json',
    },
    json={
        'profile_id': profile_id,
        'text': 'Launching today — meet our new feature.',
        'media_content_ids': [media_id],
        'publish_type': 'now',
    },
)
res.raise_for_status()
post = res.json()['data']

The response immediately includes the post object with status: "publishing". The actual handoff to the social network happens asynchronously.

4. Wait for it to publish

Poll the post until its status leaves publishing:

curl "https://api.publishbuddy.com/v1/posts/$POST_ID" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN"

When status becomes published:

url contains the live link on the social network
published_at contains the publish timestamp
social_post contains network-specific IDs (useful for fetching metrics later)

If status becomes failed:

error_message explains why
The most common causes are: expired profile connection, media that violates the network’s spec (size, aspect ratio, duration), or rate limiting on the social network’s side

Polling every 5–10 seconds is plenty — most posts complete within seconds. For high-volume integrations, consider polling only the posts you’ve recently created instead of the whole list endpoint.

5. Inspect the result

curl "https://api.publishbuddy.com/v1/posts/$POST_ID" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN" | jq '{status, url, error_message}'

For a successful Instagram post you might see:

{
  "status": "published",
  "url": "https://www.instagram.com/p/Cabc123...",
  "error_message": null
}

That’s it — you’ve published programmatically. Now learn how to schedule for later or queue across the week.

Getting started

Core concepts

How-to guides

API essentials

Publish your first post

1. Choose a target profile

2. Prepare media (optional)

3. Create the post

4. Wait for it to publish

5. Inspect the result

​1. Choose a target profile

​2. Prepare media (optional)

​3. Create the post

​4. Wait for it to publish

​5. Inspect the result

1. Choose a target profile

2. Prepare media (optional)

3. Create the post

4. Wait for it to publish

5. Inspect the result