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: Inspect connected social accounts and manage social buckets — named groups of accounts for one-shot multi-account publishing. Use this skill when the user asks "what's connected", "which accounts do I have", "show my social accounts", "create a bucket", "make a Launch Team bucket with my LinkedIn and X", "add my Instagram to the launch bucket", "rename that bucket", or says "post to my <bucket> bucket" and you need to resolve the bucket's member accounts. Connecting a new account happens in the user's browser — hand them a link via get-connect-link. Not for drafting content (use bolta-draft-post) or analytics (use bolta-analytics-report).4---56# Bolta Accounts & Buckets78Answer "what's connected" and turn natural phrases like "create a bucket called Launch9Team with my LinkedIn and X" into the right tool calls. A **bucket** is a named group of10connected accounts — publishing to a bucket hits every member at once, so buckets are how11users say "post this to the launch crew" without listing UUIDs. The connected-accounts12card these tools render has **Socials** and **Buckets** tabs — accounts on one, buckets13(with their members) on the other.1415## When to use16Any question about which social accounts are connected, plus creating, renaming, or17re-membering buckets — or resolving a bucket name into account ids for another skill.1819## Tools this skill uses20| Tool | Why |21|-|-|22| `list-workspaces` | Resolve `workspace_id` if unknown. |23| `list-accounts` | Connected accounts + their UUIDs — the ONLY source of `account_ids`. Optional `platform` filter. Renders the accounts card (Socials tab). |24| `list-buckets` | The workspace's buckets with member accounts (id, platform, username). Renders the accounts card (Buckets tab). |25| `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. |26| `create-social-bucket` | Create a bucket: `name` (unique per workspace) + `account_ids`. |27| `update-social-bucket` | Rename a bucket and/or replace its members (`account_ids` is a FULL replacement list). |28| `get-my-capabilities` | Diagnose permission errors on bucket writes (needs accounts:write). |2930## Prerequisites31- `workspace_id` — resolve once via `list-workspaces`, reuse for every call. Auth is automatic32 via the Bolta connector's OAuth grant — never ask for an API key.33- Reads need any role; creating/updating buckets needs **accounts:write** — granted to34 owner, admin, and creator. Viewers are read-only. (Elsewhere, default new content to35 Draft; confirm before publish/delete.)3637## Workflow3839### 1. Resolve the workspace40Call `list-workspaces` and use the active workspace's `id`. Never guess a UUID.4142### 2. "What's connected?"43Call `list-accounts(workspace_id)` (add `platform` if the user named one) and, in parallel,44`list-buckets(workspace_id)`. Present both halves the way the card does — Socials: each45account's platform + username + status; Buckets: each bucket's name and members. If nothing46is connected (or the platform the user wants is missing), call47`get-connect-link(workspace_id)` — pass `platform` if the user named one — and share the48URL. OAuth can't complete in chat, so the user finishes the connection in their browser;49afterwards re-check with `list-accounts`.5051### 3. Create a bucket52"Create a bucket called Launch Team with my LinkedIn and X":531. `list-accounts(workspace_id)` → match the named platforms/usernames to accounts and take54 their **base account UUIDs** (never virtual `linkedin_org_` / `facebook_page_` ids).55 If a platform matches several accounts, ask which one.562. Confirm the resolved members with the user ("Launch Team = LinkedIn @acme + X @acme — 57 create it?").583. `create-social-bucket(workspace_id, name="Launch Team", account_ids=[…])`.594. Verify: re-read with `list-buckets(workspace_id)` and confirm the new bucket and its60 members are what the user asked for before reporting success.61Bucket names are unique per workspace — an exact duplicate 409s (see failures).6263### 4. Update a bucket64"Add my Instagram to the Launch Team bucket" / "rename it":651. `list-buckets(workspace_id)` → find the bucket, note its `bucket_id` AND current members.662. Build the new membership: current member ids ± the change (ids from `list-accounts`).67 `account_ids` is a **full replacement** — sending only the new account would drop the rest.683. `update-social-bucket(workspace_id, bucket_id, account_ids=[…full new list…])`; pass69 `name` for renames. Repeating the same update is safe (idempotent).704. Verify: re-read with `list-buckets(workspace_id)` and confirm the final name/membership71 before reporting success.7273Note: there is **no delete-bucket tool** on this surface. If the user asks to delete a74bucket, say so and point them to the Bolta app; you can offer to empty or rename it via75`update-social-bucket` instead.7677### 5. "Post to my <bucket> bucket"78This skill resolves; drafting skills act. Call `list-buckets`, find the bucket by name, and79hand its member `account_ids` to **bolta-draft-post** / `create-post` (or use the bucket with80`voice-generate`'s `selectedAccountsOrBuckets`). If the named bucket doesn't exist, show the81buckets that do and offer to create it.8283## Failure handling84- Bucket name already exists (409 on create) → show the existing bucket and offer to update85 it instead of creating a duplicate.86- Permission error on create/update → run `get-my-capabilities`, report the missing87 accounts:write role plainly, don't retry.88- Named account not found → show `list-accounts` output and ask; never guess an id, and never89 pass virtual `linkedin_org_` / `facebook_page_` ids as bucket members.90- Empty bucket request (no resolvable accounts) → create with `name` only is allowed, but91 confirm the user really wants an empty bucket.9293## Example94User: "What's connected? And make a bucket called Launch Team with LinkedIn and X."951. `list-workspaces` → workspace_id.962. `list-accounts(workspace_id)` + `list-buckets(workspace_id)` → LinkedIn @acme,97 X @acme, IG @acme.shop; no buckets yet.983. "3 accounts connected (LinkedIn, X, Instagram), no buckets. Create Launch Team =99 LinkedIn @acme + X @acme?" → yes.1004. `create-social-bucket(workspace_id, name="Launch Team", account_ids=[li_id, x_id])`.1015. "Launch Team created with 2 members — say 'post to my Launch Team bucket' any time to102 hit both at once."
boltaai