Skip to main content
A workspace is the unit of ownership in PublishBuddy. It groups together:
  • The social profiles that have been connected (Instagram, X, TikTok, Facebook, LinkedIn, YouTube, Pinterest, etc.)
  • The media library (assets and folders)
  • The posts that have been planned, scheduled, or published
  • The team members who can collaborate inside it
  • The billing plan and credit balance
A user can belong to multiple workspaces — for example, a freelancer running social for several clients, or an agency with one workspace per brand. Your API token has the same workspace access as the user it was created for.

​
The workspace ID

Almost every endpoint either takes a workspace ID in the path (e.g. /workspaces/{workspace}/posts) or returns resources scoped to one (e.g. a media file’s workspace_id). Your first API call should always be:
…to discover the IDs you have access to. Cache them — workspace IDs are stable UUIDs and don’t change for the lifetime of the workspace.

​
Permissions inside a workspace

Each user holds a role inside each workspace they belong to (owner, admin, member, guest, etc.), and each role grants a set of permissions. When you call the API with a personal access token, the request is evaluated against:
  1. The token’s abilities (set when you generated it) — see Authentication.
  2. The user’s permissions in the target workspace.
Both must allow the action. For example, a token with the posts ability still cannot create a post in a workspace where the underlying user is a view-only collaborator.

​
Listing workspaces

GET /workspaces (see the API reference) returns every workspace the authenticated user is a member of. The response includes basic metadata (name, ID, plan tier) but not the full set of profiles, posts, or media — those have their own endpoints, scoped to a given workspace ID.

​
What you cannot do via the API

Some workspace-level operations are deliberately UI-only:
  • Creating a workspace — only possible from app.publishbuddy.com.
  • Inviting members — managed in the dashboard’s team settings.
  • Connecting a social profile — requires going through each network’s OAuth flow, which is a browser-only step.
  • Managing billing / plans — managed through Stripe in the dashboard.
These intentionally require a human in the loop. Once the workspace and profiles exist, everything else (uploading media, planning posts, reading analytics) is available through the API.

​
Next

Profiles

The connected social accounts inside a workspace.

Posts

Planning, scheduling, and publishing content.