Hand over a goal
Start a durable job from a goal in plain words and collect what the team makes: posts, PDF carousels, generated images, narrated short video with a designed thumbnail, or a strategy.
The job researches what wins in the market today, plans, asks when it must, and proposes; a run presses Run on the newest plan with an optional budget. A turn can carry attachments and named actors, the transcript is readable at any time, a detached run can be tailed or stopped, and the outputs land in the queue as proposals. This is the door for anything that is not a single post: make a video, design a carousel, plan a launch week. Beside the chat on the Ask page sits the panel, a read-only document the browser and a terminal share: an agent opens tabs on it (a calendar, search hits, a teleprompter, a story page that grows a chapter at a time, options to pick from), asks the person a question there and reads back the pick.
Ask in plain words
- "make a 30-second TikTok about the bug we fixed today"
- "design a five-slide carousel explaining what we do and schedule it for Saturday"
- "plan and draft a launch week across LinkedIn and X"
- "AI video generation API for social media"
- "turn this blog post into a narrated short"
From an agent host (MCP)
Server: https://shapelessai.com/mcp (add it to your host).
jobs_create: Start a durable job from a goal, optionally with files attached. The run keeps going server-side; returns the job id and its web url to poll or continue. Needs the write scope.jobs_list: List jobs with liveness and the web url of each, 200 per page, newest first. A non-null nextCursor means older jobs exist: pass it back asbefore. Needs the read scope.jobs_get: One job in full: transcript, status (queued, running, idle, failed or stopped; lastRun.reason says why a run failed or stopped), outputs (posts with queue state, media: each with url to play it and downloadUrl to save the file, both opening for the signed-in human) and its web url. Use jobs_brief when you only need enough to reply. Needs the read scope.jobs_brief: Compact context for continuing a conversation: the last messages clipped, an artifact inventory, post statuses, and the web url. Use jobs_get for the full transcript, jobs_continue to reply. Needs the read scope.jobs_tail: Watch a job's run: replays its events from the cursor, then follows live until the run ends, 60 seconds pass, or 200 events. Returns {live, cursor, events} - resume with that cursor. {live: false} means no run stream to attach to; the job may still have finished work, so read jobs_get. Needs the read scope.jobs_continue: Send another message to a job, optionally with files attached - also the way to resume a stuck or failed run with full history. Needs the write scope.jobs_run: Press Run on the job's newest proposed plan - the approval click a headless caller has nobody to make. Use it after a turn ended with a plan waiting; deliverables still land as proposed drafts. Needs the write scope.jobs_stop: Stop a running job. Needs the write scope.panel_open: The panel is the document beside the chat on the ShapelessAI Ask page (shapelessai.com/studio): tabs the person looks at while you talk, and the place they answer a question with a press or edit a plan's node by hand. The browser, the chat's own agent and you (from a terminal) share one panel per conversation. The page draws it for the founder's account today (it is being rolled out); every account holds and can read its panel through these tools and the API. Opens one tab and brings it to the front; the same id replaces that tab in place, so re-open to refresh it rather than piling up copies. Kinds and their fields: node: a graph node (person, account, organization, post) with its connections: node (a node id like person:<uuid>). people: the account's people graph: no fields. plan: a chat turn's plan cards: messageId, blockIds. calendar: the post queue as a calendar: ids? (post ids, none = whole queue), highlight? (post ids to point at), from?, to?, mode? (week | month | list). performance: how posts performed: post? (one post id), days?. agent: a standing agent and its runs: strategyId?. choices: a question the person answers with one press: question, options [{id, label, sub?, media? {kind: image|video, src}}]; use panel_ask, which also waits for the pick. prompter: a teleprompter for recording: sections [{text, kind?, seconds?, cue?, wpm? (this section's pace, 60..260), tone? (warm, urgent, dry...)}], wordsPerMinute?; text may carry delivery marks: words land harder, / a breath, // a full stop, ^word lifts. search: search results the person can group and sort: query, hits [{id, title, sub?, kind?, node?, url?, thumb?, group? {facet: value}, metrics? {name: number}}], groupBy?, orderBy?. brain: the account's Brand Memory: no fields. media: images, videos or audio to look at: items [{kind: image|video|audio, src, title?}]. custom: your own HTML in a sandboxed frame, when no kind fits: html (at most 200 KB), height?. flow: a plan as a graph, one node per choice made for the person: nodes [{id, kind, title, sub?, status? (planned | new | changed | running | done | failed | waiting), costUsd?, text?, refs? [{title, url?, node?, why?}], media? {kind: image|video|audio, src, title?}, options? [string], was?}] (1 to 40, unique ids), edges [{from, to, label?}], estimateUsd?, approve? (the sentence the Approve press sends to the chat). story: one growing page of chapters in the order things happened, for a list of posts, a side by side, options, a comparison or a product walked: chapters [{id, kind, title, note?, ...}] (1 to 16, unique ids) where kind is references {refs [{node (a post on the graph, asset:...) or url (http(s), a page, product, repository or paper off the graph; exactly one), title, kind? (post | page | product | code | research; post with node, required with url), fit? (high | mid | low), why?, picked?, proof? [{value, label, source?, asOf?}] (at most 4 measured facts, e.g. {value: "41,237", label: "stars"}), excerpt? (at most 600 characters: a file snippet or a quoted claim), thumb? (a media key or an http(s) image)}] (1 to 30, one row per node or url), leftOut? [reason]} | frames {seconds [n] (1 to 8), rows [{id, label, sub?, node?, frames [{src?, badge?, note?}] (one per second; no src draws the planned frame with note), vs?, take?, you?}] (1 to 8)} | options {options [{id, label, sub?, text?, media? {kind, src}, refs? [asset node], chips? [string], count?}] (2 to 4), picked?, approve? (the sentence the Approve press sends)} | compare {sides [{label, node?, url?, ours?, median?}] (2 to 12; with two, theirs then the person's; at most one ours and one median), rows [{label, values [number | null] (one per side, null when unknown), unit?, better? (higher | lower)}] (1 to 24)} | shots {shots [{src, caption?, step?, flag?}], facts? [{value, label}]}; every src is a media key, a /path or an http(s) URL; add or replace one chapter later with panel_update's chapter. The person ticks references, picks an option and leaves one-line marks on any row, option, measure, frame or shot (marks [{chapter, target, text}]); read them back with panel_watch. Returns {conversation_id, id, panel, text}; text is one plain line per tab. Needs the write scope.panel_update: The panel is the document beside the chat on the ShapelessAI Ask page (shapelessai.com/studio): tabs the person looks at while you talk, and the place they answer a question with a press or edit a plan's node by hand. The browser, the chat's own agent and you (from a terminal) share one panel per conversation. The page draws it for the founder's account today (it is being rolled out); every account holds and can read its panel through these tools and the API. Changes fields of an open tab (a new title, more search hits, the calendar's highlight); its kind never changes. On a story, chapter adds the next chapter or replaces the one with its id in place, so the page grows without resending it. An id not on the panel changes nothing. Needs the write scope.panel_close: The panel is the document beside the chat on the ShapelessAI Ask page (shapelessai.com/studio): tabs the person looks at while you talk, and the place they answer a question with a press or edit a plan's node by hand. The browser, the chat's own agent and you (from a terminal) share one panel per conversation. The page draws it for the founder's account today (it is being rolled out); every account holds and can read its panel through these tools and the API. Closes one tab. Needs the write scope.panel_ask: Asks the person a question they answer with one press: two or more options (a hook, a thumbnail, a time slot), shown on the panel; with wait_seconds it waits for the press. The panel is the document beside the chat on the ShapelessAI Ask page (shapelessai.com/studio): tabs the person looks at while you talk, and the place they answer a question with a press or edit a plan's node by hand. The browser, the chat's own agent and you (from a terminal) share one panel per conversation. The page draws it for the founder's account today (it is being rolled out); every account holds and can read its panel through these tools and the API. Returns {conversation_id, id, picked: {optionId, label, at} | null, panel_rev}; null means not answered yet, so call panel_watch with after_rev to keep waiting. Asking again with the same id replaces the question and clears its answer. Needs the write scope.panel_watch: The panel is the document beside the chat on the ShapelessAI Ask page (shapelessai.com/studio): tabs the person looks at while you talk, and the place they answer a question with a press or edit a plan's node by hand. The browser, the chat's own agent and you (from a terminal) share one panel per conversation. The page draws it for the founder's account today (it is being rolled out); every account holds and can read its panel through these tools and the API. Reads the panel: every tab, which one is in front, and every answered question in picks. With after_rev (the panel.rev you last saw) and wait_seconds it waits until something changes, the way to hear the person's press. Returns {conversation_id, panel, text, picks: [{id, optionId, label, at}]}. Needs the read scope.
From code (REST)
Bearer API key with the scope each call names (auth, OpenAPI).
GET /api/v1/jobs(read scope): Jobs with liveness, one page.POST /api/v1/jobs(write scope): Start a durable job from a goal: {goal, label?, budgetUsd?, timezone?, attachments?, characters?, autoRun?, panel?, referenceId?, mode?}. panel true gives the run the war-room panel and the identity graph tools. referenceId is a member id from GET /api/v1/references; mode is clone|format|inspiration (default inspiration). Send an Idempotency-Key so a retry never starts a second job.GET /api/v1/jobs/{id}(read scope): One job: transcript, status (queued, running, idle, failed, stopped), lastRun {state, ending, reason}, outputs.POST /api/v1/jobs/{id}/messages(write scope): Another turn on the job: {text, budgetUsd?, timezone?, attachments?, autoRun?, panel?}. A job whose panel holds tabs keeps the panel without panel being sent again.POST /api/v1/jobs/{id}/run(write scope): Run the job's newest proposed plan, as the Run button does: {budgetUsd?}. 202 while it runs.POST /api/studio(write scope): One agent turn, NDJSON stream of studio events.GET /api/studio/tail(read scope): Re-attach to a detached run's event log.POST /api/studio/stop(write scope): Stop a detached run.PUT /api/studio/attachments/{filename}(write scope): Upload a chat attachment; returns its mediaKey.POST /api/studio/uploads(write scope): Open a resumable upload session.PUT /api/studio/uploads/{sessionId}(write scope): Send one chunk of a resumable upload.POST /api/studio/uploads/complete(write scope): Close a resumable upload; returns its mediaKey.GET /api/conversations(read scope): Thread list, one page.GET /api/conversations/{id}(read scope): One transcript with each post artifact's queue state. Read with a key or a token it leaves the thread unread for its person; only their browser, or POST .../opened, marks it opened.PATCH /api/conversations/{id}(write scope): Rename a thread.DELETE /api/conversations/{id}(write scope): Delete a thread.POST /api/conversations/{id}/opened(write scope): Mark a thread opened.GET /api/conversations/{id}/panel(read scope): The war room's panel for this thread: the read-only document beside the chat on the Ask page, which the browser and a terminal share. Returns {conversationId, panel: {rev, items, active?, suggestions}, text}; text is one plain line per item. With ?after=<rev>&wait=<seconds> it waits up to 25 s for a change.POST /api/conversations/{id}/panel(write scope): Change the panel: {ops: [...]} folded in order through the one reducer the browser uses, returning the new {conversationId, panel, text}. A malformed op is a 400 naming what is wrong.GET /api/conversations/current/panel(read scope): The panel of the thread the account opened last (the chat most likely open in the browser), with its conversationId, so a terminal can drive it without an id. Same ?after=&wait= as the per-thread route.
The body
POST /api/conversations/{id}/panel:
opsarray, required: open {item, focus?}: show a tab (same item id replaces it in place). update {id, patch, focus?}: change fields of a tab, never its kind. show {id}: bring a tab to the front. close {id}. pick {id, optionId}: the person's answer to a choices tab; on a story, pick {id, chapter, ref} ticks or unticks a reference and pick {id, chapter, optionId} picks one option of that chapter. chapter {id, chapter, focus?}: add one chapter to a story, or replace the one with the same id in place. mark {id, chapter, target, text}: the person's one-line note on something in a story (target names it in words). edit {id, node, patch {title?, text?, sub?, media?}}: the person's hand edit of one flow node (marked changed, the old value kept as was); edit {id, section, patch {text, cue?}}: their hand edit of one teleprompter section. suggest {suggestions: [{label, prompt, sub?, icon?}]}: the chips under the chat.
From a terminal (CLI)
shapeless jobs createshapeless jobs listshapeless jobs showshapeless jobs continueshapeless jobs runshapeless jobs tailshapeless jobs stopshapeless panel showshapeless panel openshapeless panel updateshapeless panel closeshapeless panel askshapeless panel watch
Example
Refusals
| Status | Meaning |
|---|---|
| 409 | code idempotency_in_flight: the first request with this Idempotency-Key is still running (Retry-After). |
Where else
More in The agent team
Run standing agents · Run the manager · Know what ShapelessAI can do · Cast actors and voices
