Quickstart

This guide walks you end-to-end from “no token” to “scheduled post”. You’ll need:

A PublishBuddy account at app.publishbuddy.com
At least one social profile connected to that account (Instagram, X, Facebook, etc.)
curl or any HTTP client of your choice

1. Get an API token

If you don’t have one yet, follow the Authentication walkthrough:

Open the dashboard

Go to User Settings → Login & Security

Click your avatar → User Settings, then open the Login & Security tab.

Generate an API token

Click Generate API token, tick the abilities you need (for this quickstart, enable workspaces, profiles, media_contents, and posts), and copy the value somewhere safe.

Export it to your shell so the rest of the snippets work as-is:

export PUBLISHBUDDY_TOKEN="pb_1|xxx..."

2. List your workspaces

Every resource in PublishBuddy is scoped to a workspace, so the first call always tells you which workspaces your token can see.

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

A successful response looks like:

{
  "data": [
    {
      "id": "9b1f2c3d-5a6e-7f8a-9b0c-1d2e3f4a5b6c",
      "name": "Acme Marketing",
      "...": "..."
    }
  ]
}

Copy the id of the workspace you want to work with:

export WORKSPACE_ID="9b1f2c3d-5a6e-7f8a-9b0c-1d2e3f4a5b6c"

A profile represents one connected social account inside the workspace (e.g. your Instagram business account, or your brand’s X profile).

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

Pick the profile you want to publish to and store its ID:

export PROFILE_ID="3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d"

If you don’t have any profiles yet, connect one inside the dashboard first — profiles are connected through each network’s OAuth flow, which is a UI-only step.

4. Upload a piece of media

Posts can contain text, links, and media. To attach an image or video, upload it to the media library first. Uploads go directly to storage in three steps: presign, upload, confirm. First, ask the API for a pre-signed upload URL:

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": "hello-world.jpg", "mime": "image/jpeg", "size": 184293 }] }'

You’ll get back a temporary media id and an upload_url:

{
  "data": [
    {
      "id": "9b1f2c3d-5a6e-7f8a-9b0c-1d2e3f4a5b6c",
      "upload_url": "https://storage.publishbuddy.com/...?X-Amz-Signature=...",
      "upload_headers": { "x-amz-acl": "public-read" },
      "upload_method": "PUT",
      "expires_in": 1800,
      "...": "..."
    }
  ]
}

Upload the file bytes straight to that URL, replaying the signed headers:

curl -X PUT "$UPLOAD_URL" \
  -H "x-amz-acl: public-read" \
  --data-binary @./hello-world.jpg

Then confirm the upload to finalize the media item:

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": ["9b1f2c3d-5a6e-7f8a-9b0c-1d2e3f4a5b6c"] }'

Save the media ID — it’s the same UUID you presigned and confirmed:

export MEDIA_ID="9b1f2c3d-5a6e-7f8a-9b0c-1d2e3f4a5b6c"

5. Publish a post

Combine everything: the profile to publish to, the text, and the media.

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": "Hello from the PublishBuddy API!",
    "media_content_ids": ["'"$MEDIA_ID"'"],
    "publish_type": "now"
  }'

The response includes the new post and its status (waiting, publishing, published, etc.):

{
  "data": {
    "id": "post_4c5d6e7f...",
    "status": "publishing",
    "friendly_status": "Publishing",
    "text": "Hello from the PublishBuddy API!",
    "...": "..."
  },
  "message": "Post created"
}

To schedule instead of publishing immediately, set "publish_type": "schedule_using_fixed_datetime" and add "publish_at": "2026-12-25T09:00:00Z". To add the post to a profile’s posting queue, use "publish_type": "queue_using_timeslots". See Schedule posts for the full lifecycle.

6. Check the post’s status

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

When status becomes published, the url field will contain the live post’s URL on the social network.

Next steps

Core concepts

Understand workspaces, profiles, posts, and the publish lifecycle.

Schedule posts

Three ways to control when a post goes live.

Analyze performance

Read profile, workspace, and best-time analytics.

Full API reference

Every endpoint, parameter, and response shape.

Getting started

Core concepts

How-to guides

API essentials

1. Get an API token

2. List your workspaces

4. Upload a piece of media

5. Publish a post

6. Check the post’s status

Next steps

Core concepts

Schedule posts

Analyze performance

Full API reference

​1. Get an API token

​2. List your workspaces

​3. List the workspace’s social profiles

​4. Upload a piece of media

​5. Publish a post

​6. Check the post’s status

​Next steps

Core concepts

Schedule posts

Analyze performance

Full API reference

1. Get an API token

2. List your workspaces

3. List the workspace’s social profiles

4. Upload a piece of media

5. Publish a post

6. Check the post’s status

Next steps