Bolta Accounts & Buckets
Answer "what's connected" and turn natural phrases like "create a bucket called Launch
Team with my LinkedIn and X" into the right tool calls. A bucket is a named group of
connected accounts — publishing to a bucket hits every member at once, so buckets are how
users say "post this to the launch crew" without listing UUIDs. The connected-accounts
card these tools render has Socials and Buckets tabs — accounts on one, buckets
(with their members) on the other.
When to use
Any question about which social accounts are connected, plus creating, renaming, or
re-membering buckets — or resolving a bucket name into account ids for another skill.
Tools this skill uses
| Tool |
Why |
list-workspaces |
Resolve workspace_id if unknown. |
list-accounts |
Connected accounts + their UUIDs — the ONLY source of account_ids. Optional platform filter. Renders the accounts card (Socials tab). |
list-buckets |
The workspace's buckets with member accounts (id, platform, username). Renders the accounts card (Buckets tab). |
get-connect-link |
URL to Bolta's connect page for when nothing (or the wrong platform) is connected. Optional platform preselects it on the page. |
create-social-bucket |
Create a bucket: name (unique per workspace) + account_ids. |
update-social-bucket |
Rename a bucket and/or replace its members (account_ids is a FULL replacement list). |
get-my-capabilities |
Diagnose permission errors on bucket writes (needs accounts:write). |
Prerequisites
workspace_id — resolve once via list-workspaces, reuse for every call. Auth is automatic
via the Bolta connector's OAuth grant — never ask for an API key.- Reads need any role; creating/updating buckets needs accounts:write — granted to
owner, admin, and creator. Viewers are read-only. (Elsewhere, default new content to
Draft; confirm before publish/delete.)
Workflow
1. Resolve the workspace
Call list-workspaces and use the active workspace's id. Never guess a UUID.
2. "What's connected?"
Call list-accounts(workspace_id) (add platform if the user named one) and, in parallel,
list-buckets(workspace_id). Present both halves the way the card does — Socials: each
account's platform + username + status; Buckets: each bucket's name and members. If nothing
is connected (or the platform the user wants is missing), call
get-connect-link(workspace_id) — pass platform if the user named one — and share the
URL. OAuth can't complete in chat, so the user finishes the connection in their browser;
afterwards re-check with list-accounts.
3. Create a bucket
"Create a bucket called Launch Team with my LinkedIn and X":
list-accounts(workspace_id) → match the named platforms/usernames to accounts and take
their base account UUIDs (never virtual linkedin_org_ / facebook_page_ ids).
If a platform matches several accounts, ask which one.- Confirm the resolved members with the user ("Launch Team = LinkedIn @acme + X @acme —
create it?").
create-social-bucket(workspace_id, name="Launch Team", account_ids=[…]).- Verify: re-read with
list-buckets(workspace_id) and confirm the new bucket and its
members are what the user asked for before reporting success.
Bucket names are unique per workspace — an exact duplicate 409s (see failures).
4. Update a bucket
"Add my Instagram to the Launch Team bucket" / "rename it":
list-buckets(workspace_id) → find the bucket, note its bucket_id AND current members.- Build the new membership: current member ids ± the change (ids from
list-accounts).
account_ids is a full replacement — sending only the new account would drop the rest.
update-social-bucket(workspace_id, bucket_id, account_ids=[…full new list…]); pass
name for renames. Repeating the same update is safe (idempotent).- Verify: re-read with
list-buckets(workspace_id) and confirm the final name/membership
before reporting success.
Note: there is no delete-bucket tool on this surface. If the user asks to delete a
bucket, say so and point them to the Bolta app; you can offer to empty or rename it via
update-social-bucket instead.
5. "Post to my bucket"
This skill resolves; drafting skills act. Call list-buckets, find the bucket by name, and
hand its member account_ids to bolta-draft-post / create-post (or use the bucket with
voice-generate's selectedAccountsOrBuckets). If the named bucket doesn't exist, show the
buckets that do and offer to create it.
Failure handling
- Bucket name already exists (409 on create) → show the existing bucket and offer to update
it instead of creating a duplicate.
- Permission error on create/update → run
get-my-capabilities, report the missing
accounts:write role plainly, don't retry.
- Named account not found → show
list-accounts output and ask; never guess an id, and never
pass virtual linkedin_org_ / facebook_page_ ids as bucket members.
- Empty bucket request (no resolvable accounts) → create with
name only is allowed, but
confirm the user really wants an empty bucket.
Example
User: "What's connected? And make a bucket called Launch Team with LinkedIn and X."
list-workspaces → workspace_id.list-accounts(workspace_id) + list-buckets(workspace_id) → LinkedIn @acme,
X @acme, IG @acme.shop; no buckets yet.- "3 accounts connected (LinkedIn, X, Instagram), no buckets. Create Launch Team =
LinkedIn @acme + X @acme?" → yes.
create-social-bucket(workspace_id, name="Launch Team", account_ids=[li_id, x_id]).- "Launch Team created with 2 members — say 'post to my Launch Team bucket' any time to
hit both at once."
1---2name: bolta-accounts-and-buckets3description: >4 Inspect connected social accounts and manage social buckets — named groups of accounts5 for one-shot multi-account publishing. Use this skill when the user asks "what's6 connected", "which accounts do I have", "show my social accounts", "create a bucket",7 "make a Launch Team bucket with my LinkedIn and X", "add my Instagram to the launch8 bucket", "rename that bucket", or says "post to my <bucket> bucket" and you need to9 resolve the bucket's member accounts. Connecting a new account happens in the user's10 browser — hand them a link via get-connect-link. Not for drafting content (use11 bolta-draft-post) or analytics (use bolta-analytics-report).12---1314# Bolta Accounts & Buckets1516Answer "what's connected" and turn natural phrases like "create a bucket called Launch17Team with my LinkedIn and X" into the right tool calls. A **bucket** is a named group of18connected accounts — publishing to a bucket hits every member at once, so buckets are how19users say "post this to the launch crew" without listing UUIDs. The connected-accounts20card these tools render has **Socials** and **Buckets** tabs — accounts on one, buckets21(with their members) on the other.2223## When to use24Any question about which social accounts are connected, plus creating, renaming, or25re-membering buckets — or resolving a bucket name into account ids for another skill.2627## Tools this skill uses28| Tool | Why |29|-|-|30| `list-workspaces` | Resolve `workspace_id` if unknown. |31| `list-accounts` | Connected accounts + their UUIDs — the ONLY source of `account_ids`. Optional `platform` filter. Renders the accounts card (Socials tab). |32| `list-buckets` | The workspace's buckets with member accounts (id, platform, username). Renders the accounts card (Buckets tab). |33| `get-connect-link` | URL to Bolta's connect page for when nothing (or the wrong platform) is connected. Optional `platform` preselects it on the page. |34| `create-social-bucket` | Create a bucket: `name` (unique per workspace) + `account_ids`. |35| `update-social-bucket` | Rename a bucket and/or replace its members (`account_ids` is a FULL replacement list). |36| `get-my-capabilities` | Diagnose permission errors on bucket writes (needs accounts:write). |3738## Prerequisites39- `workspace_id` — resolve once via `list-workspaces`, reuse for every call. Auth is automatic40 via the Bolta connector's OAuth grant — never ask for an API key.41- Reads need any role; creating/updating buckets needs **accounts:write** — granted to42 owner, admin, and creator. Viewers are read-only. (Elsewhere, default new content to43 Draft; confirm before publish/delete.)4445## Workflow4647### 1. Resolve the workspace48Call `list-workspaces` and use the active workspace's `id`. Never guess a UUID.4950### 2. "What's connected?"51Call `list-accounts(workspace_id)` (add `platform` if the user named one) and, in parallel,52`list-buckets(workspace_id)`. Present both halves the way the card does — Socials: each53account's platform + username + status; Buckets: each bucket's name and members. If nothing54is connected (or the platform the user wants is missing), call55`get-connect-link(workspace_id)` — pass `platform` if the user named one — and share the56URL. OAuth can't complete in chat, so the user finishes the connection in their browser;57afterwards re-check with `list-accounts`.5859### 3. Create a bucket60"Create a bucket called Launch Team with my LinkedIn and X":611. `list-accounts(workspace_id)` → match the named platforms/usernames to accounts and take62 their **base account UUIDs** (never virtual `linkedin_org_` / `facebook_page_` ids).63 If a platform matches several accounts, ask which one.642. Confirm the resolved members with the user ("Launch Team = LinkedIn @acme + X @acme — 65 create it?").663. `create-social-bucket(workspace_id, name="Launch Team", account_ids=[…])`.674. Verify: re-read with `list-buckets(workspace_id)` and confirm the new bucket and its68 members are what the user asked for before reporting success.69Bucket names are unique per workspace — an exact duplicate 409s (see failures).7071### 4. Update a bucket72"Add my Instagram to the Launch Team bucket" / "rename it":731. `list-buckets(workspace_id)` → find the bucket, note its `bucket_id` AND current members.742. Build the new membership: current member ids ± the change (ids from `list-accounts`).75 `account_ids` is a **full replacement** — sending only the new account would drop the rest.763. `update-social-bucket(workspace_id, bucket_id, account_ids=[…full new list…])`; pass77 `name` for renames. Repeating the same update is safe (idempotent).784. Verify: re-read with `list-buckets(workspace_id)` and confirm the final name/membership79 before reporting success.8081Note: there is **no delete-bucket tool** on this surface. If the user asks to delete a82bucket, say so and point them to the Bolta app; you can offer to empty or rename it via83`update-social-bucket` instead.8485### 5. "Post to my <bucket> bucket"86This skill resolves; drafting skills act. Call `list-buckets`, find the bucket by name, and87hand its member `account_ids` to **bolta-draft-post** / `create-post` (or use the bucket with88`voice-generate`'s `selectedAccountsOrBuckets`). If the named bucket doesn't exist, show the89buckets that do and offer to create it.9091## Failure handling92- Bucket name already exists (409 on create) → show the existing bucket and offer to update93 it instead of creating a duplicate.94- Permission error on create/update → run `get-my-capabilities`, report the missing95 accounts:write role plainly, don't retry.96- Named account not found → show `list-accounts` output and ask; never guess an id, and never97 pass virtual `linkedin_org_` / `facebook_page_` ids as bucket members.98- Empty bucket request (no resolvable accounts) → create with `name` only is allowed, but99 confirm the user really wants an empty bucket.100101## Example102User: "What's connected? And make a bucket called Launch Team with LinkedIn and X."1031. `list-workspaces` → workspace_id.1042. `list-accounts(workspace_id)` + `list-buckets(workspace_id)` → LinkedIn @acme,105 X @acme, IG @acme.shop; no buckets yet.1063. "3 accounts connected (LinkedIn, X, Instagram), no buckets. Create Launch Team =107 LinkedIn @acme + X @acme?" → yes.1084. `create-social-bucket(workspace_id, name="Launch Team", account_ids=[li_id, x_id])`.1095. "Launch Team created with 2 members — say 'post to my Launch Team bucket' any time to110 hit both at once."
boltaai