Run BetterSocials from your own agent

One API key runs the whole product. An AI agent — Claude, Claude Code, Codex, anything that speaks JSON over HTTP — can read the unified inbox and reply to comments and DMs, create, caption, schedule and publish posts, manage comment-keyword automations and calendar notes, read analytics, and do full video edits in Studio. These are the same routes the app itself calls, so every validation, credit meter and guard applies to an agent exactly as it applies to a person clicking.

Two things stay human on purpose: video Export (rendering runs in the browser, so a person presses the button after checking the work), and anything that touches money, account settings or channel connections — those never accept a key at all.

If you just want your AI assistant to run your BetterSocials, you can skip the rest of this page. There is no key to copy and nothing to install: paste one address into the app you already use, then sign in when it asks.

https://bettersocials.ai/api/mcp

Claude (claude.ai, desktop or mobile): Settings → Connectors → Add custom connector. Name it BetterSocials, paste the address above, then Add and Connect. Claude opens a BetterSocials sign-in, you approve, and the tools show up in your next chat. Custom connectors need a paid Claude plan.

ChatGPT: Settings → Developer mode (under Plugins) to turn it on, then close Settings and open Plugins in the left sidebar. The plugin is made there, not on the settings screen. Hit the plus button, name it BetterSocials, leave Connection on Server URL and paste the address above, leave Authentication on OAuth, tick “I understand and want to continue” (Create stays disabled until you do), and Create. ChatGPT walks you through the same sign-in and approval, and you switch it on per chat from the composer’s plus menu under Developer mode. Developer mode needs a paid ChatGPT plan on the web, and write actions ask you to confirm each time.

Both doors ask for a name and neither enforces one. Use BetterSocials in both anyway: the name is how you aim a prompt at these tools, and every example here says “use the BetterSocials tools”.

The connection acts with your workspace’s normal limits, and Settings → Connected apps in BetterSocials disconnects it in one click.

Every key is scoped to one workspace, stored as a SHA-256 hash, revocable in one click, and rate-limited in three tiers: reads (600 per 5 minutes), writes (120), and sends — anything that leaves the app onto a real social account — at 30. Tripped limits page our security channel. Key management, billing, account settings and channel connect/disconnect stay session-only, so a leaked key can never mint more keys, spend money, or deprovision an account. Sends run through the same claim locks and failure ledger the app uses — an agent cannot send around a guard. Repeated invalid keys get throttled per network and page us too.

Every response from the agent surface carries a docs object linking to https://bettersocials.ai/api/meta — the live manifest of every endpoint, rule and limit. Point your agent at it once and it always knows what it can do, including things we shipped after you wrote your integration. The MCP server exposes the same thing as the get_capabilities tool.

Mint an API key in Settings → API keys. Keys are shown once, stored as a SHA-256 hash, capped at five active per workspace, and scoped to that workspace — an id in a URL never reaches across. Key management itself stays in the app, so a leaked key can never mint or revoke keys.

curl -s https://bettersocials.ai/api/studio/editor/projects \
  -H "Authorization: Bearer br_YOUR_KEY"

The hosted MCP server wraps the same contract as tools, over Streamable HTTP. One command in Claude Code:

claude mcp add --transport http bettersocials https://bettersocials.ai/api/mcp \
  --header "Authorization: Bearer br_YOUR_KEY"

Tools cover the same surface: get_inbox, get_thread, send_reply, draft_reply, create_post, generate_captions, list_queues, list_keywords, create_keyword, get_analytics, list_connections, the Studio project tools, create_upload_url, and more — get_capabilities always lists the current set.

1. Read. GET the project. The whole edit is one JSON document — clips, cuts, captions, overlays, effects, sounds. Keep the updatedAt you read.
2. Modify. Change the document in memory. Cuts are kept source ranges; overlay, effect and sound times are output seconds.
3. Write. PATCH the whole document back with baseUpdatedAt. A stale base is a 409 — re-read, re-apply, retry. Identical content is a free no-op.
4. Watch. Any open editor tab applies your patch live within about a second, and the creator can undo it with ⌘Z like their own edit.

Media bytes never ride the document. Ask POST /api/studio/editor/media/upload for a signed URL, PUT the file straight to storage, then reference the returned publicUrl as a clip or overlay sourceUrl. The open editor fetches it once into its local vault. Supply analysis (word timings plus measured speech bounds) with a clip and the editor never re-charges transcription.

• Auth: `Authorization: Bearer br_…` — mint keys in Settings → API keys (shown once, 5 active per workspace, SHA-256 at rest). Every workspace has API access. A presented key is judged alone; key management stays in-session.
• MCP without a key: claude.ai and ChatGPT connect through OAuth. Paste the MCP endpoint into their connector settings and sign in when asked. The granted token has the same authority and limits as an API key, and Settings → Connected apps disconnects it instantly.
• The workspace is resolved from the key. Ids in URLs never cross workspaces.
• Every bearer call is rate limited per workspace in three tiers: reads 600/5min, writes 120/5min, sends 30/5min — MCP tools included. A 429 carries Retry-After — back off and retry; tripped limits alert our security channel. Repeated invalid keys are throttled per network.
• Sends are sacred: send_reply / publishNow / publishDraft / retry act on the creator’s REAL social accounts. Do them only on explicit instruction or standing rules the creator set. Every send passes the same claim locks, account resolution and failure ledger the app itself uses.
• Session-only forever: key management, billing, account/profile, workspace management, and connecting/disconnecting channels. A leaked key can never mint keys, spend money, or deprovision an account.
• AI generation (drafts, captions) spends the workspace’s credits exactly like the in-app buttons — an agent can never generate more cheaply than a human.
• PATCH replaces the whole document. A partial doc is a valid doc with everything else missing — always GET → modify → PATCH. For a small change (captions, title card, speed, a cut) use /projects/:id/edits (MCP: edit_project) instead: no round-trip, and every op answers applied-or-why-not.
• Optimistic concurrency: send `baseUpdatedAt` (the `updatedAt` you read). Stale = 409 → re-GET, re-apply, re-PATCH.
• Identical-content PATCHes are no-ops — retries are free and never fight an open editor tab.
• Docs are sanitized both directions: unknown fields drop, numbers clamp. Diff the response against what you sent.
• Media bytes never ride the doc. Upload via /media/upload (or host them yourself) and reference the URL as `sourceUrl` on clips, overlays, sounds and green-screen backgrounds; any open editor ingests it once into its local vault.
• Sandboxed and cannot PUT to storage? Never a dead end: POST /media/import fetches a public URL server-side into the bucket (MCP: import_media), or the creator drops the file into the composer and GET /media/uploads (MCP: list_media) finds it.
• Supply `analysis` (ASR words + measured speech bounds) with a clip and the editor never re-charges transcription.
• Every successful write pings open editor tabs live (≈1s). Agent edits land as undo steps — ⌘Z works on them.
• Export stays human: rendering is client-side by design, so a person presses Export in the tab. Everything up to that button is yours.
• Uploaded media not referenced by any project document within 48 hours is swept.

Every BetterSocials workspace has API access — sign up, mint a key in Settings → API keys, and go. Something missing that your agent needs? Tell us through the in-app support chat — gaps in this surface get closed fast, and the manifest at /api/metais how you’ll see them land.