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, Threads, Bluesky, Telegram, Google Business Profile)
  • The media library (assets and folders)
  • The posts that have been planned, scheduled, or published
  • The team members who collaborate inside it
  • The billing plan and AI credit balance of the workspace owner
A user can belong to multiple workspaces: 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, limited to workspaces whose owner is on Pro or Business.

​
The workspace ID

Almost every endpoint either takes a workspace ID in the path (for example /workspaces/{workspace}/posts) or returns resources scoped to one (for example a profile’s workspace_id). Your first API call should always be:
This discovers the IDs you have access to. Cache them: workspace IDs are stable UUIDs and do not change for the lifetime of the workspace.

​
Listing workspaces

GET /workspaces returns every workspace the authenticated user is a member of, ordered by name. Each entry carries three fields:
avatar is null when the workspace has no image. Profiles, posts, and media have their own endpoints, scoped to a workspace ID. The response does not include the plan; plan limits surface as 402 responses instead (see Plans).

​
Permissions inside a workspace

Each user holds a role in each workspace they belong to, and editors additionally get an access level per profile. 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 role and access level in the target workspace.
Both must allow the action. A token with the posts ability still cannot create a post in a workspace where the underlying user has no access to the target profile. Drafts with no profile need admin rights, because they are not tied to any profile the editor has access to. Profile access works the same way everywhere it applies: the profile list, profile and workspace analytics, hashtags, best times, and the MCP server. The owner sees every profile. Everyone else sees the profiles they have been given access to, plus every public profile (competitor accounts added for analytics only). Asking for analytics on a profile you can’t access returns 403.

​
Plans

The REST API and the MCP server both follow the plan of the workspace owner, not the plan of the user who holds the token. A workspace is open to the API when its owner is on Pro or Business, so an invited member can use the API and MCP in a Business workspace even from a Free account of their own. A workspace whose owner is on Free is closed to everyone, and requests into it return 402. The user who holds the token still needs a Pro or Business plan of their own, or membership of at least one Pro or Business workspace. Once neither holds, every request returns 402. See Plans for the details and for the endpoint groups that need a specific feature.

​
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 and plans: handled 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.