Know the connected accounts
Which social accounts the account holds, as identity only (never a token), each with the connectionId every post and queue call takes.
Connecting one is the platform's own sign-in, so a person has to click: the agent mints a one-time link for the platform and hands it over, and a post or job that needs an account it does not hold answers with that link. Track a handle by name without connecting it, sort accounts into groups, and read TikTok's creator info before each TikTok post, as TikTok requires. The rail's rules per platform, the limits it enforces before a post goes out, and who the credential belongs to (plan and credit balance) live beside it.
Ask in plain words
- "which accounts are connected"
- "give me a link to connect my TikTok"
- "how long can an X post be"
- "which plan am I on and how much credit is left"
From an agent host (MCP)
Server: https://shapelessai.com/mcp (add it to your host).
connections_list: Connected social accounts (identity only, no tokens), plusconnect: one clickable link per platform with no live account, andreconnecton an expired one. Hand the link to the human. Needs the read scope.connections_link: The one URL the human clicks to connect a social account on a platform (connections_list already carries one per missing platform). Lasts 15 minutes, works only signed in as this account; the platform's own OAuth follows in the browser, then the account shows in connections_list. Needs the write scope.platforms_list: Every platform the rail posts to: text limit, media rules, whether documentTitle is required, first-comment support, and the JSON Schema for its settings. Read it before posts_create. Works with any key (read scope or none).me: Who this credential belongs to: email, plan, credit balance. Needs the read scope.email_settings: Which emails ShapelessAI sends this account: one switch per kind (a post went live, a post failed, a video is ready, drafts ready to approve, a plan limit reached, an agent paused on budget, the weekly summary), each with what it is, whether it is on and its default for the account's plan (an account on a paid plan gets only the three it must act on unless it switches more on), plus the last mails sent. With no arguments it only reads. Passkindandenabledto turn one on or off, when the human asks to: a sign-in code is not a kind and always arrives. Reading needs the read scope, changing the write scope.
From code (REST)
Bearer API key with the scope each call names (auth, OpenAPI).
GET /api/connections(read scope): Connected social accounts (identity only, never tokens).DELETE /api/connections(publish scope): Disconnect an account (?id=). Ends our ability to publish there, so it costs publish. An id this account does not hold answers ok and changes nothing.POST /api/connections/link(write scope): The one URL the human opens to connect a social account: {platform}. Lasts 15 minutes, works only signed in as this account; the platform's own OAuth follows.PATCH /api/connections/{id}(write scope): Move an account into a group: {groupId} or null for ungrouped.GET /api/connections/{id}/tiktok-creator-info(read scope): TikTok's creator info for that connection: privacy levels, limits. Read it before every TikTok post; TikTok forbids caching it.GET /api/connections/permissions(no key): Per platform: what connecting asks the person to allow, in plain words from the scopes we really request (allows), and the two lines the connect card shows (approval: we only post what they approve;permissions: the platform's ask and how to disconnect).POST /api/connections/tracked(write scope): Track an account by handle, no OAuth, never a publish target: {platform, handle, followers?}.GET /api/groups(read scope): Account groups.POST /api/groups(write scope): Create a group: {name, color?}.PATCH /api/groups(write scope): Reorder groups: {orderedIds}.PATCH /api/groups/{id}(write scope): Rename or recolor a group.DELETE /api/groups/{id}(write scope): Delete a group; its accounts become ungrouped.GET /api/platforms(no key): Every platform the rail posts to: limits, media rules, settings schema, first-comment support.GET /api/me(read scope): Who am I: account, plan, credit balance,posting(on the Free plan, today's and this UTC month's posts against their limits, with reset times; null on a paid plan) andnext: the moves worth making on this account now, the skill and the docs.GET /api/me/email(read scope): Which emails this account gets:kinds, one switch per kind of mail (post-published, publish-failed, video-ready, posts-ready, limit-reached, agent-blocked, weekly-digest) with its label, what it is, whether it is on and its default for the account's plan (a paid plan gets only publish-failed, posts-ready and agent-blocked unless a kind is switched on), and the last emails we sent.PUT /api/me/email(write scope): Body { kind, enabled } turns one kind of email on or off; { kinds: { <kind>: true | false } } several. Answers every switch as it now stands. A sign-in code is not a kind and always arrives.
The body
POST /api/connections/link:
platformstring, required: A platform id from GET /api/platforms with oauth: true.
From a terminal (CLI)
shapeless connectionsshapeless platformsshapeless whoamishapeless loginshapeless logout
Example
Refusals
| Status | Meaning |
|---|---|
| 400 | No ?id=. |
| 400 | Not a platform with oauth: true. |
| 400 | The body is not JSON, or groupId is neither a group id nor null. |
| 404 | No such group, or no such connection on this account. |
| 404 | No TikTok connection with that id on this account. |
| 409 | The connection's token expired or would not refresh; error says so. Reconnect the account. |
| 429 | TikTok's per-token rate limit; retry after the Retry-After seconds. |
| 400 | Unknown platform, or no handle. |
