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

# Quickstart

> Schedule your first post in under five minutes.

Postbreeze is a social media scheduling platform that lets you
manage and publish content across all major platforms from a single
API.

## Install the SDK

<CodeGroup>
  ```bash npm theme={null}
  npm install @postbreeze/node
  ```

  ```bash pnpm theme={null}
  pnpm add @postbreeze/node
  ```

  ```bash yarn theme={null}
  yarn add @postbreeze/node
  ```
</CodeGroup>

## Authentication

Postbreeze authenticates every request with a Bearer API key. Keys
look like `pb_live_<random>` and are mintable from the dashboard.

### Getting your API key

Open **Settings → Developers → New API key** in the
[dashboard](https://postbreeze.ai/dev/api-keys). Leave **Full
access** toggled ON for the simplest setup — the key will work
across every workspace you belong to.

### Set up the client

```ts theme={null}
import Postbreeze from "@postbreeze/node";

const postbreeze = new Postbreeze({
  apiKey: process.env.POSTBREEZE_API_KEY!,
});
```

## Key concepts

Four foundational primitives in Postbreeze:

* **Workspaces** — containers that group connected accounts, posts,
  and team members together (think "brands" or "clients")
* **Social accounts** — your connected Instagram, X, TikTok, etc.,
  belonging to a workspace
* **Posts** — content to publish, schedulable to multiple accounts
  across platforms simultaneously
* **Media** — images and videos uploaded to your library, reusable
  across posts

## Step 1: Create a workspace

A workspace is the top-level tenant. If you're an agency managing
multiple brands, create one workspace per brand.

<CodeGroup>
  ```ts SDK theme={null}
  const workspace = await postbreeze.workspaces.create({
    name: "Acme Co.",
  });

  console.log(workspace.id);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.postbreeze.ai/api/v1/workspaces \
    -H "Authorization: Bearer $POSTBREEZE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "name": "Acme Co." }'
  ```
</CodeGroup>

Save the `id` value — you'll need it for the next step.

## Step 2: Connect a social account

Now connect a social media account to the workspace. This uses
OAuth, so it returns an `authorizeUrl` that the user opens in a
browser to grant access.

<CodeGroup>
  ```ts SDK theme={null}
  const { authorizeUrl } = await postbreeze.socialAccounts.connect({
    workspaceId: workspace.id,
    platform: "INSTAGRAM",
  });

  console.log("Open this URL:", authorizeUrl);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.postbreeze.ai/api/v1/social-accounts/connect \
    -H "Authorization: Bearer $POSTBREEZE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "workspaceId": "wsp_…",
      "platform": "INSTAGRAM"
    }'
  ```
</CodeGroup>

Open the URL in a browser to authorize Postbreeze. After authorization,
the platform redirects back and the account is connected to your
workspace.

### Available platforms

`INSTAGRAM`, `FACEBOOK_PAGE`, `X`, `LINKEDIN_PERSON`,
`LINKEDIN_COMPANY`, `TIKTOK_PERSONAL`, `TIKTOK_BUSINESS`, `YOUTUBE`,
`PINTEREST`, `THREADS`, `BLUESKY`.

## Step 3: Get your connected accounts

List the accounts your key can act on. By default the call returns
**every account across every workspace** — each row carries its own
`workspaceId`.

<CodeGroup>
  ```ts SDK theme={null}
  const accounts = await postbreeze.socialAccounts.list();

  for (const account of accounts) {
    console.log(`${account.platform}: @${account.handle} (${account.id})`);
  }
  ```

  ```bash cURL theme={null}
  curl https://api.postbreeze.ai/api/v1/social-accounts \
    -H "Authorization: Bearer $POSTBREEZE_API_KEY"
  ```
</CodeGroup>

To narrow the list to a single workspace, pass `workspaceId`:

```ts theme={null}
const acmeAccounts = await postbreeze.socialAccounts.list({
  workspaceId: workspace.id,
});
```

## Step 4: Schedule your first post

Use an `accountId` from the previous step. The workspace is derived
from the account — no `workspaceId` argument needed here.

<CodeGroup>
  ```ts SDK theme={null}
  const post = await postbreeze.posts.create({
    content: "Hello from the Postbreeze API! 👋",
    scheduledFor: new Date(Date.now() + 60_000).toISOString(),
    platforms: [{ accountId: accounts[0].id }],
  });

  console.log("Scheduled:", post.id);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.postbreeze.ai/api/v1/posts \
    -H "Authorization: Bearer $POSTBREEZE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "content": "Hello from the Postbreeze API! 👋",
      "scheduledFor": "2026-06-15T09:00:00Z",
      "platforms": [{ "accountId": "soc_…" }]
    }'
  ```
</CodeGroup>

Your post is now scheduled and will publish automatically at the
specified time.

### Posting to multiple platforms

Add more entries to the `platforms` array to cross-post the same
content. Same caption goes to every account unless you override it
per-platform with `captionOverride`.

```ts theme={null}
await postbreeze.posts.create({
  content: "Same caption, three platforms.",
  scheduledFor: "2026-06-15T09:00:00Z",
  platforms: [
    { accountId: "soc_ig_123" },
    { accountId: "soc_x_456" },
    { accountId: "soc_tiktok_789" },
  ],
});
```

### Publishing immediately

To publish right now instead of scheduling, set `scheduledFor` to a
few seconds in the future:

```ts theme={null}
await postbreeze.posts.create({
  content: "Going live right now.",
  scheduledFor: new Date(Date.now() + 5_000).toISOString(),
  platforms: [{ accountId: "soc_…" }],
});
```

### Creating a draft

To save a post without scheduling, omit `scheduledFor`:

```ts theme={null}
await postbreeze.posts.create({
  content: "Draft — not scheduled yet.",
  platforms: [{ accountId: "soc_…" }],
});
```

The post is saved with status `DRAFT` and won't publish until you
later call `posts.schedule({ postId, scheduledAt })`.

## What's next?

* [Platform guides](/platforms/overview) — Instagram, TikTok, X, …
* [Adding media](/concepts/scheduling) — images, videos, URL ingest
* [Webhooks](/concepts/webhooks) — react to events as they happen
* [Workspaces](/concepts/workspaces) — multi-tenant patterns
* [MCP install](/mcp/install) — drive Postbreeze from Claude / Cursor