> ## Documentation Index
> Fetch the complete documentation index at: https://docs.publishbuddy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> A workspace is the top-level container in PublishBuddy. Everything else — profiles, posts, media — belongs to one.

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:

```bash theme={null}
curl https://api.publishbuddy.com/v1/workspaces \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN"
```

…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](/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](/api-reference/introduction)) 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](https://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

<CardGroup cols={2}>
  <Card title="Profiles" icon="user" href="/concepts/profiles">
    The connected social accounts inside a workspace.
  </Card>

  <Card title="Posts" icon="paper-plane" href="/concepts/posts">
    Planning, scheduling, and publishing content.
  </Card>
</CardGroup>