> ## 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.

# Social profiles

> Profiles represent each connected social account inside a workspace.

A **profile** is one connected social account inside a workspace — for example "Acme's Instagram business account" or "Acme on X". Each profile is tied to exactly one social network, holds the OAuth credentials needed to publish on that user's behalf, and is the target of every [Post](/concepts/posts) you create.

## Anatomy of a profile

A profile response includes:

* `id` — UUID, stable across the profile's lifetime
* `name` — human-readable label shown in the dashboard
* The **network** it belongs to (Instagram, X, Facebook, TikTok, YouTube, LinkedIn, Pinterest, etc.)
* The **connection state** (active, expired, requires reconnection)
* Network-specific metadata (handle, page ID, business account ID, etc.)

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

See `GET /workspaces/{workspace}/profiles` in the [API reference](/api-reference/introduction) for the full schema.

## Connecting a profile

Profile connection happens entirely in the dashboard — there is **no API endpoint to connect a new profile**, because every supported network requires going through its own browser-based OAuth consent flow.

To add a profile:

1. Sign in to [app.publishbuddy.com](https://app.publishbuddy.com).
2. Open the workspace.
3. Go to **Profiles → Connect new profile**.
4. Choose the network, complete the OAuth handshake, and grant the required permissions.

Once connected, the profile is immediately usable from the API.

## When a profile needs reconnection

Social networks expire OAuth tokens periodically — sometimes on a schedule, sometimes when the user changes their password or revokes access. When that happens, the profile's connection state flips to `requires_reconnection` and any post targeting it will fail with an `error_message` explaining the cause.

The API does not let you complete the OAuth refresh — the user has to reconnect from the dashboard, the same way they originally connected. Monitor profile connection state if you build dashboards on top of the API, and surface a "Reconnect in PublishBuddy" prompt to your users when needed.

## Profile vs SocialProfileEntity

You'll occasionally see references to **`social_profile_entity`** in the API (especially on Pinterest posts, where the entity is the Board the pin goes to). An entity is a sub-resource *inside* a profile — think of it as "this profile has several boards / channels / playlists, and the post targets a specific one".

Most networks don't use entities — for Instagram, X, Facebook (page), TikTok, etc., the profile is the only thing you target. Pinterest is the main case where you'll need to pick an entity (the board) when creating a post.

## Per-network quirks

Different networks expose different fields on a post (privacy status on YouTube, board ID on Pinterest, commercial content flags on TikTok, trial parameters on Instagram Reels, etc.). The `PostResource` schema includes nullable fields for all of these — only the ones relevant to the target profile's network are meaningful.

| Network         | Notable fields                                                        |
| --------------- | --------------------------------------------------------------------- |
| **Instagram**   | `trial_params` (Reels), supports image/video/carousel/Reel post types |
| **TikTok**      | `post_visibility`, `commercial_content_type`, `interaction_ability`   |
| **YouTube**     | `title`, `category`, `license`, `privacy_status`                      |
| **Pinterest**   | `target_url`, `social_profile_entity` (board)                         |
| **X (Twitter)** | text + up to 4 images or 1 video                                      |
| **Facebook**    | page-level publishing only                                            |
| **LinkedIn**    | personal profile and company page posting                             |

The dashboard's post composer applies the right field set per network — when scripting against the API, refer to the relevant endpoint's request schema for the supported parameters.

## Next

<Card title="Posts" icon="paper-plane" href="/concepts/posts">
  How to plan, schedule, and publish content to one or many profiles.
</Card>