# Social accounts

Connected network accounts. Connecting one happens in the dashboard.

Connect social accounts in the dashboard (**Social → Connect**), then schedule
posts, work the inbox of comments and DMs, and run comment-to-DM automations
from here. Connecting an account needs a person at a browser — the networks'
sign-in screens are theirs, not ours — so there is no endpoint that connects
one.

Every id below is a uuid we issued. A network's own ids for your posts appear
where you need them (`post_external_ids` on an automation); the network ids of
**other people** — the person who commented, the person who messaged you —
never do. You get their public handle and display name, which is what the
network shows anyone.

Needs `social:read` to read and `social:write` to change anything. Leads need
`leads:read`.

## Accounts

```json
{
  "id": "a3d9f1c4-7b2e-4c60-9e85-1f4b6d2a0c73",
  "network": "instagram",
  "handle": "acme",
  "display_name": "Acme Supply Co.",
  "avatar_url": "https://example.com/avatar.jpg",
  "status": "active",
  "last_error": null,
  "connected_at": "2026-09-30T10:02:11.004211+00:00",
  "capabilities": {
    "publish": true,
    "comments": true,
    "hide_comment": true,
    "dms": true,
    "private_reply": true,
    "webhooks": true,
    "max_body_length": 2200,
    "max_media": 10,
    "text_only": false,
    "video": true
  }
}
```

`network` is one of `instagram`, `facebook`, `threads`, `bluesky`, `x`,
`tiktok`, `linkedin`, `youtube`, `pinterest`. `status` is `active`,
`needs_reauth` (the network ended our access — reconnect it in the dashboard;
`last_error` says why) or `disconnected`. `capabilities` says what this
account can do on its network: a Threads account has no DMs, an Instagram
account cannot post text alone.

## Operations

### `GET /v1/accounts`

**List connected accounts**

Scope `social:read`.

Every connected account and what its network supports. Never paged (`next_cursor` is always null).

**Answers**

| Status | Body |  |
|---|---|---|
| 200 | `AccountList` | The accounts. |
| 401 | `ErrorEnvelope` | `UNAUTHORIZED`: no key, or one that is malformed, unknown or revoked. It never says which. |
| 403 | `ErrorEnvelope` | `INSUFFICIENT_SCOPE`: the key lacks this operation's scope. Or `ORGANISATION_SUSPENDED`: the key's organisation is suspended. Never about another workspace's object, which is 404. |
| 429 | `ErrorEnvelope` | `RATE_LIMITED`: too many requests. Wait for `Retry-After` seconds. |
| 500 | `ErrorEnvelope` | `INTERNAL_ERROR`: ours. Safe to retry; send the same `Idempotency-Key` on a POST. |

**The connected accounts** — answers `200`

`capabilities` says what each account's network allows, so a client can hide what would be refused rather than discovering it on publish.

```bash
curl https://api.boltclaw.ai/v1/accounts \
  -H "Authorization: Bearer bc_live_EXAMPLExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

```js
const res = await fetch("https://api.boltclaw.ai/v1/accounts", {
  headers: {
    Authorization: `Bearer ${process.env.BOLTCLAW_KEY}`,
  },
});

// 200
const data = await res.json();
```

## Shapes

The objects these operations send and answer.

### Account

| Field | Type |  |
|---|---|---|
| `id` | `uuid` | (**required**) |
| `network` | `Network` | (**required**; one of `instagram`, `facebook`, `threads`, `bluesky`, `x`, `tiktok`, `linkedin`, `youtube`, `pinterest`) |
| `handle` | `string \| null` | (**required**) |
| `display_name` | `string \| null` | (**required**) |
| `avatar_url` | `string \| null` | (**required**) |
| `status` | `string` | (**required**; one of `active`, `needs_reauth`, `disconnected`) |
| `last_error` | `string \| null` | (**required**) |
| `connected_at` | `date-time` | (**required**) |
| `capabilities` | `Capabilities` | (**required**) |

### AccountList

| Field | Type |  |
|---|---|---|
| `data` | `Account[]` | (**required**) |
| `next_cursor` | `NullCursor` | Always null; this list is never paged. (**required**) |

### Capabilities

| Field | Type |  |
|---|---|---|
| `publish` | `boolean` | (**required**) |
| `comments` | `boolean` | (**required**) |
| `hide_comment` | `boolean` | (**required**) |
| `dms` | `boolean` | (**required**) |
| `private_reply` | `boolean` | (**required**) |
| `webhooks` | `boolean` | (**required**) |
| `max_body_length` | `integer` | (**required**) |
| `max_media` | `integer` | (**required**) |
| `text_only` | `boolean` | (**required**) |
| `video` | `boolean` | (**required**) |

### Network

One of: `instagram`, `facebook`, `threads`, `bluesky`, `x`, `tiktok`, `linkedin`, `youtube`, `pinterest`.

### NullCursor

Always null; this list is never paged.

`any | null`.

<!-- https://boltclaw.ai/docs/api/social-accounts as markdown. Generated from openapi.yaml; API version 1.22.0. -->
<!-- Every /docs page answers as markdown: add .md to its path, or send Accept: text/markdown. -->