Hand over a goal

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.

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 as before. Needs the read scope.
• jobs_get: One job in full: transcript, running/idle status, outputs (posts with queue state, media) 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.

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?}.
• GET /api/v1/jobs/{id} (read scope): One job: transcript, status, outputs.
• POST /api/v1/jobs/{id}/messages (write scope): Another turn on the job.
• 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.
• 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.

From a terminal (CLI)#

• shapeless jobs create
• shapeless jobs list
• shapeless jobs show
• shapeless jobs continue
• shapeless jobs run
• shapeless jobs tail
• shapeless jobs stop

Example#

curl -s https://shapelessai.com/api/v1/jobs -H "Authorization: Bearer $SHAPELESS_API_KEY" -H "Content-Type: application/json" -d '{"goal":"A 30-second vertical video about our new pricing page, captions on, our voice.","budgetUsd":2}'

// MCP tool call
{ "tool": "jobs_create", "arguments": { "goal": "A 30-second vertical video about our new pricing page, captions on, our voice.", "autoRun": true } }

shapeless jobs create "A 30-second vertical video about our new pricing page, captions on, our voice."

Where else#

• Do it in the studio
• The jobs docs (markdown)