API reference

Everything an agent can reach over HTTPS, and the scope each route needs. The studio in a browser rides a signed session cookie; an agent outside that browser rides an API key - the same account, the same routes, a second credential.

curl -H "Authorization: Bearer slk_..." https://shapelessai.com/api/me

Minting a key, the three scopes and the refusal codes are on Authentication. Putting a post out is on Posts. This page is the whole surface.

Machine-readable#

curl -s https://shapelessai.com/api/openapi.json

OpenAPI 3.1 for every key-accepting route, no auth. Point a generator at it rather than reading this page, if that is what you are doing. The rendered operation list is at the bottom of this page.

The same spec is a ready Postman collection in the public ShapelessAI API workspace (team profile: ShapelessAI on Postman). Fork it, set SHAPELESS_API_KEY to your key, and send GET /api/me.

It is also listed on RapidAPI as ShapelessAI on RapidAPI, all 119 operations. Through RapidAPI's gateway send your X-RapidAPI-Key and also Authorization: Bearer slk_...; the gateway passes the Bearer key through, so calls run on your own ShapelessAI account and plan.

Paging#

The thread lists - GET /api/conversations and GET /api/v1/jobs - answer 200 rows per page, newest first, alongside a nextCursor. Non-null means older rows exist: send it back verbatim as ?before=<nextCursor> for the next page, and keep going until it is null. The cursor is the last row's sort key (<updatedAtISO>~<id>), so a thread touched while you page is never skipped or served twice; anything else is a 400. ?origin= on the jobs list filters the page it answers, so a page can carry fewer than 200 jobs and still have a cursor - follow the cursor, not the count.

Routes that accept a key#

Every row is enforced in the codebase by src/server/auth/route-scopes.test.ts: if a route and this table disagree, the build fails.

Identity and accounts#

Chat#

Jobs#

The durable alternative to stream plumbing. A job is a conversation whose ids the server mints: you send a goal, get a 202 with the job's id, and the run keeps going whether or not you stay connected. Poll the job for its transcript and outputs, or tail the live stream. Posting another message to a job builds the conversation history server-side from the stored transcript, so sending "continue" to a failed or stuck job resumes it.

A running job streams into the same event log chat uses: follow it with GET /api/studio/tail?conversationId=<id>, stop it with POST /api/studio/stop. The label becomes the job's title; without one the goal's first line is. Refusals are the plan turn's: 402 when the month's free credits are spent, 429 when planning too fast, 400 for an attachment the account cannot use.

Attaching files

attachments puts files on the message itself - the same thing the web composer's paperclip does, and the agent sees them: an image's pixels are inlined for that turn, video and PDF go over by storage URI, and the media key is named in the text so it survives in history after the pixels are gone. Up to 6 per message; each entry needs a name and either text (inlined, 24k characters) or a mediaKey:

{
  "goal": "Does this thumbnail work for the launch post?",
  "attachments": [
    { "name": "thumb.png", "mediaKey": "chat-uploads/<account>/thumb-mt1z.png", "contentType": "image/png" },
    { "name": "notes.md", "text": "Launch is Thursday. Tone: plain, no hype." }
  ]
}

Get a mediaKey by uploading the bytes to PUT /api/studio/attachments/[filename] (10MB images, 30MB video/PDF; filenames are [A-Za-z0-9._-]). Any media key the account owns also works - a brand asset from workspace-assets/, media an earlier run produced - because the server copies it into this account's chat-uploads/ prefix before the turn, which is the only prefix the engine reads. A key belonging to another account is a 400 naming the file, not a run that dies halfway. A malformed entry is a 400 too: attachments are never dropped silently.

References#

The creators, competitors and peers an account works from, the people we suggest, and a browse of what other workspaces picked (counts of 3 or more only). See MCP for the whole loop.

POST /api/v1/jobs takes referenceId (a member id) and mode (clone, format or inspiration, the default) to work from that person; POST /api/posts takes the same provenance as inspiration: {kind, id, mode?, memberId?}.

Shapeless Graph#

The graph of who is who on social. Reads are free; a pull holds its budget on the wallet and is charged what it cost. See Identity for the controls and the stream.

Labels and an edge's confirmed or rejected status are written on the shared graph, so they stay with the founder's session for now and refuse a key.

Posts#

POST /api/posts takes {connectionId, postText, mediaKeys?, documentTitle?, scheduledAt?, queue?, settings?, firstComment?}. scheduledAt omitted or in the past publishes now; queue: true takes the account's next free posting slot instead (GET /api/connections/[id]/queue shows the slots). settings follows the platform's settingsSchema from GET /api/platforms (TikTok privacyLevel, Reddit subreddit, YouTube privacyStatus); documentTitle is required on YouTube. firstComment is posted as the post's own first reply the moment it is live: LinkedIn (1250 chars), X (280), Bluesky (300); other platforms answer 422. A platform rule that refuses the post answers 422 with the rule in error. The Free plan posts ten a day, counted on the UTC day of the slot: the eleventh answers 402 {code: "free_daily_cap", limit, day, resetsAt}. Paid plans have no cap. The row's firstCommentUrl / firstCommentError say what became of the comment.

GET /api/posts returns the newest 50 rows by slot (?limit= up to 200), narrowed server-side by ?status= (any of proposed, scheduled, publishing, published, handoff, failed, canceled). ?sort=views instead ranks published posts over the whole history by their latest reading's impressions (views), most viewed first, narrowed by ?platform=, ?connectionId=, ?minViews= and ?since= (ISO). ?fresh=1 first re-reads, from the platforms, the numbers of the listed posts whose reading is older than 6 hours (up to 25 posts, so the answer can take ~30 s); without it every reading is as of its own fetchedAt. GET /api/posts/[id] returns the same shape for one row. Two fields close the loop between what an agent meant and what happened:

• inspiration - what the post was made from: {kind, id, lane?, title?, url?} where kind is format-card, topical-story or reference-post. Set it on a delivery through the artifact's inspiredBy meta (the object, or a JSON string of it); anything malformed is dropped, never an error. null when nobody said.
• metrics - how a published post did, null for anything not published and for a published post we hold no reading for yet: {latest, at24h, at7d, lift, baseline: {platform, n, median, scoredBy}}. Each sample is {fetchedAt, impressions, reactions, comments, shares}; at24h and at7d are the first readings taken at or after that age, null until one exists. Sampling slows as a post ages, so on a sparsely sampled post the "24h" reading can be days late - fetchedAt on the sample is what says how late, and it is on every sample for exactly that reason. Lift is this post's score divided by the median score of the same account's published posts on the same platform over the trailing 90 days
  • 2 means it did twice its channel's median. It is null when fewer than five scored posts stand behind that median (baseline.n says how many do), because a two-post median invents findings. baseline.scoredBy is impressions where the platform reports reach and engagements where it does not - the same rule the Performance screen ranks by.

/api/posts/[id]/boost takes {budgetCents, days, objective} (engagement or traffic) and spends nothing: it creates a proposed boost action, and only POST /api/actions/[id]/send on that action creates the Meta campaign. The budget is the campaign's lifetime cap, billed by Meta to the connected ad account. It refuses (402) without an active paid plan (the Free plan does not qualify), and (409) when the post is not a published Facebook Page or Instagram post with a known platform id, or when no active Meta ad account is connected.

GET /api/posts/[id]/comments answers {postId, platform, comments[], lastReadIso} from our own ledgers - it never calls a platform. Each comment carries {id, authorHandle, text, url, atIso, isOwn, replyVerdict, reply}, where reply is the drafted action bound to it ({actionId, text, status, verdict, error, url, sentAtIso}) or null. POST with {commentId, text} stages that reply as a proposed reply action - the same row the approvals inbox holds - which POST /api/actions/[id]/send then sends; it refuses (409) when the platform has no sanctioned reply path for that comment (replyVerdict: "task"). /comments/refresh runs the same engagement poll Cloud Tasks fires after publishing, and only spends credits when there is a new comment to draft a reply to.

Agents (strategies) and the manager#

Characters (actors)#

An actor is workspace-level identity - a face, a voice, a style, a memory - that posts and agents CAST. characters on a job is that cast, by slug or id; the agent is shown the account's whole roster either way, so it can reuse an actor that fits instead of inventing another one. A ref that names nobody is a 400 naming it, never a run that silently stars nobody.

POST /api/characters/[id]/voice takes one of:

• {action: "design", voicePrompt} - writes a voice from casting direction. The direction is KEPT on the character and shown to the agent on every run.
• {action: "clone", sampleMediaKey, consent: true} - clones a 5-10s sample already in the account. consent is the caller attesting they hold the rights; it is stored.
• {action: "speak", text} - reads text in the actor's current voice, returns a mediaKey.

A creation SPENDS CREDIT: the answer carries costUsd (what the provider billed us) and the account is debited for it at the tier's rate, ledgered under voice:<design|clone>:<id>. An empty wallet is a 402 with the same trial_exhausted code a run gives - never a silent no-voice. speak is not a creation and is not billed here.

Engagement actions#

Paid campaigns#

POST /api/ads/campaigns/[id] takes {adAccountId, status?, budgetCents?, endsAt?} with absolute targets (status is ACTIVE or PAUSED, budgetCents is in the budget's own kind, daily or lifetime, and endsAt is an ISO date in the future). A change that can only lower spend (pause, lower budget, earlier end) applies at once and answers {outcome: "applied", settings}. One that could raise it (resume, higher budget, a later end on a daily budget) spends nothing yet: it answers 201 {outcome: "proposed", action} with a proposed campaign_change action, and only POST /api/actions/[id]/send on that action applies it. Raising needs an active paid plan (402), and one waiting change per campaign (409). Only Meta campaigns are supported today.

Brand Memory, assets and media#

Analytics#

Profile audit#

Tools#

Every tool the studio agent holds, callable on its own - the same code, so the API never does a different thing from the agent. GET /api/tools (no key) lists each one with its JSON Schema input and default price. The body of a call is that input, plus an optional budgetUsd (default 2, max 10); the credit is held for the budget and settled at what the call really cost.

curl -s https://shapelessai.com/api/images -H "Authorization: Bearer $SHAPELESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"founder desk","prompt":"A quiet founder desk at dusk, one lamp, deep shadows.","aspectRatio":"4:5"}'

A file the tool made comes back in media with its URL; put its key on POST /api/posts mediaKeys to publish it. Refusals: 400 the input does not match the schema (the message names the field), 402 not enough credit (the body carries upgrade links for the human) or the call costs more than budgetUsd, 404 no such tool, 422 the tool refused the input, 502 the tool failed. A refusal or failure is never charged. Upload a video to edit with POST /api/studio/uploads first; its mediaKey is the input.

Speech. voice is one of six narrator voices - Sulafat (female, warm), Charon (male, informative; the default), Kore (female, firm), Achird (male, friendly), Erinome (female, clear), Schedar (male, even) - or pass character (an id or slug from GET /api/characters) to read in that character's designed or cloned voice. energy is calm, confident (default), energetic or hype; style adds direction in plain words.

curl -s https://shapelessai.com/api/speech -H "Authorization: Bearer $SHAPELESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"We ship on Friday. Here is what changed.","voice":"Kore","energy":"energetic"}'

Captions. The same ear the video editor cuts by: every word timed, cut into cues of at most two 42-character lines and six seconds. names spells your brand your way. The file text comes back inline in output.text as well as filed at output.captionsKey. Burned-in captions are POST /api/videos/edit.

Planned routes#

A planned capability's route exists and answers 501 {code: "not_live", want, docs, sketch} until it ships; in /api/openapi.json it is marked x-status: planned. The list, the sketches and the want door are on Capabilities.

Cookie-only, on purpose#

These refuse a bearer key. It is not an oversight:

• Key management (/api/keys, /api/keys/[id]) - a key must never be able to mint itself a wider key. A leaked read key stays a leak, not a foothold.
• Money (/api/checkout, /api/portal) - buying and cancelling belong to the person paying.
• Claiming a wiki key (/api/wiki/keys/claim) - the signed-in person says yes to a key an agent already holds, on the activation page.
• Sign-in (/api/auth/*) and the platform OAuth flows (every /api/connections/<platform> start and callback) - browser redirect flows carrying platform grants. An agent gets the human there with POST /api/connections/link; the identity list, the link, groups, tracked accounts and disconnect all take a key.
• Founder metrics (/api/metrics/agent-lanes*) and /metrics - gated on FOUNDER_EMAILS.
• Webhooks and platform callbacks (/api/polar/webhook, /api/meta/*, /api/subscribe) - they carry their own signatures.
• Internal cron (/api/internal/*) - x-internal-key, unchanged.
• Dev (/api/dev/*) and the daily-brief routes (/api/brain/brief/*), which are browser surfaces today.

The other two faces#

The CLI and the MCP server are this same contract, wrapped. There is one implementation of every operation underneath and one scope policy judging it, so anything you can do here you can do there, and the refusals are identical.