Quickstart

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

A PublishBuddy account on the Pro or Business plan (the 14-day trial works) 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 key

In the API Keys section click Generate API Key, tick the scopes you need (for this quickstart, enable Workspaces, Profiles, Media contents, and Posts), and copy the value somewhere safe. The dashboard calls tokens API keys and abilities scopes.

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

export PUBLISHBUDDY_TOKEN="aBcDeF..."

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" \
  -H "Accept: application/json"

A successful response looks like:

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

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" \
  -H "Accept: application/json"

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. Send the file in a multipart/form-data request:

curl -X POST "https://api.publishbuddy.com/v1/workspaces/$WORKSPACE_ID/media_contents" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN" \
  -H "Accept: application/json" \
  -F "files[]=@./hello-world.jpg"

The response is 201 with the new media item, active and ready to use:

{
  "data": [
    {
      "id": "9b1f2c3d-5a6e-7f8a-9b0c-1d2e3f4a5b6c",
      "name": "hello-world-k3j9xq.jpg",
      "link": "https://cdn.publishbuddy.com/...",
      "status": "active",
      "error_message": null,
      "...": "..."
    }
  ],
  "message": "Media uploaded successfully!"
}

You can also send a public URL instead, as JSON: { "url": "https://example.com/hello-world.jpg" }. An image by URL comes back active the same way; a video comes back processing and needs a moment before a post can use it. See Upload and manage media. Save the media ID:

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 "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "posts": [
      {
        "profile_id": "'"$PROFILE_ID"'",
        "content": "Hello from the PublishBuddy API!",
        "media_ids": ["'"$MEDIA_ID"'"],
        "status": "waiting",
        "publish_type": "now"
      }
    ]
  }'

The response is 201 Created with data as an array of the created posts (the endpoint accepts up to 10 items per request, one per target profile, and stamps them all with a shared group_id):

{
  "data": [
    {
      "id": "9b1f2c3d-...",
      "group_id": "2f39921e-...",
      "profile_id": "3a4b5c6d-...",
      "content": "Hello from the PublishBuddy API!",
      "status": "waiting",
      "publish_type": "now",
      "...": "..."
    }
  ],
  "message": "Post(s) created successfully."
}

To schedule instead of publishing immediately, set "publish_type": "schedule_using_fixed_datetime" and add "scheduled_for": "2026-12-25T09:00:00Z" (UTC unless you give an offset or a timezone field). 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/9b1f2c3d-..." \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN" \
  -H "Accept: application/json"

When status becomes published, the post is live and published_at holds the publish time. post_url, the post’s public link on the network, fills in with the next daily analytics sync, up to 24 hours later. See Analyze performance for its metrics.

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