> **Shapeless capabilities index**
> Fetch https://shapelessai.com/llms.txt to discover every page before exploring further.
> Every page also answers Markdown: append `.md` to its path, or send `Accept: text/markdown`.

# Hand over a goal

*Verified 2026-10-07. Source: https://shapelessai.com/capabilities/run-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.

## 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](https://shapelessai.com/connect)).

- `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](https://shapelessai.com/docs/auth), [OpenAPI](https://shapelessai.com/api/openapi.json)).

- `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

```bash
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}'
```
```jsonc
// MCP tool call
{ "tool": "jobs_create", "arguments": { "goal": "A 30-second vertical video about our new pricing page, captions on, our voice.", "autoRun": true } }
```
```bash
shapeless jobs create "A 30-second vertical video about our new pricing page, captions on, our voice."
```

## Where else

- [Do it in the studio](https://shapelessai.com/studio)
- [The jobs docs](https://shapelessai.com/docs/jobs) ([markdown](https://shapelessai.com/docs/jobs.md))