### Install Gemini CLI extension

Source: https://shapelessai.com/docs/integrations

Installs the ShapelessAI extension for Gemini CLI from the repository.

```bash
gemini extensions install https://github.com/FirstClassTree/shapelessai
```

--------------------------------

### Install Claude Code plugin for Shapeless

Source: https://shapelessai.com/docs/integrations

Adds the Shapeless plugin marketplace and installs the shapeless plugin in Claude Code. After installation, use /mcp to select shapeless and authenticate.

```text
/plugin marketplace add FirstClassTree/shapelessai
/plugin install shapeless@shapeless
```

--------------------------------

### POST /api/studio

Source: https://shapelessai.com/docs/api

Starts a studio session.

```APIDOC
## POST /api/studio

### Description
Starts a studio session.

### Method
POST

### Endpoint
/api/studio

```

--------------------------------

### Install shapelessai-ai-sdk and ai

Source: https://shapelessai.com/docs/ai-sdk

Install the package with npm. Requires Node 18 or newer, with ai 6+ and zod 3.25 or 4 as peer dependencies.

```bash
npm install shapelessai-ai-sdk ai
```

--------------------------------

### Worked error examples (402 and 422)

Source: https://shapelessai.com/docs/posts

Example error responses for the 402 free daily cap and 422 platform rule violations. The 402 includes 'code', 'limit', 'day', 'resetsAt', and 'upgrade' fields; the 422 examples show messages naming the violated rule.

```jsonc
// 402
{"code":"free_daily_cap",
 "error":"The Free plan posts 10 a day and 2026-09-22 (UTC) is full. Pick another day, or upgrade for unlimited posts.",
 "limit":10,"day":"2026-09-22","resetsAt":"2026-09-23T00:00:00.000Z",
 "upgrade":{"pricing":"https://shapelessai.com/pricing",
            "checkout":[{"tier":"spark","name":"Spark","priceUsd":35,"monthlyCreditUsd":30,
                         "url":"https://shapelessai.com/api/checkout?tier=spark"}, ...]}}

// 422
{"error":"Takes at most 4 images (this post has 7)."}
{"error":"Needs a video before it can publish."}
{"error":"Takes images OR a video in one post, never both - drop one kind."}
{"error":"instagram has no first comment: it is supported on LinkedIn, X and Bluesky."}
```

--------------------------------

### TikTok per-platform settings example

Source: https://shapelessai.com/docs/posts

Example of the settings object for TikTok. Requires explicit privacyLevel and other fields. isAigc defaults to true for AI-generated content.

```jsonc
{
  "privacyLevel": "PUBLIC_TO_EVERYONE",  // or MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY
  "disableComment": false,
  "disableDuet": false,
  "disableStitch": false,
  "commercialContent": false,            // the disclosure toggle
  "brandOrganic": false,                 // "your brand" - promotional content
  "brandContent": false,                 // a paid partnership
  "isAigc": true                         // AI-generated; our posts default this on
}
```

--------------------------------

### Install shapeless CLI with npx or npm

Source: https://shapelessai.com/docs/cli

Use npx for a one-off run or npm install globally to keep the 'shapeless' command on your PATH. Requires Node 20 or newer.

```bash
npx shapelessai --help      # one-off
npm i -g shapelessai        # keeps `shapeless` on your PATH
```

--------------------------------

### jobs_create

Source: https://shapelessai.com/docs/mcp.md

Start a durable run from a goal.

```APIDOC
## Tool: jobs_create

### Description
Start a durable run from a goal.

### Scope
`write`

### Behavior
- Requires write scope.
```

--------------------------------

### GET /api/workspace/onboarding

Source: https://shapelessai.com/docs/api

Retrieves workspace onboarding information.

```APIDOC
## GET /api/workspace/onboarding

### Description
Retrieves workspace onboarding information.

### Method
GET

### Endpoint
/api/workspace/onboarding

```

--------------------------------

### GET /api/workspace/onboarding

Source: https://shapelessai.com/docs/index.md

Retrieves onboarding questions that need to be answered.

```APIDOC
## GET /api/workspace/onboarding

### Description
Retrieves onboarding questions that need to be answered.

### Method
GET

### Endpoint
/api/workspace/onboarding

### Response
#### Success Response (200)
- **questions** (array) - List of open questions.

#### Response Example
{
  "questions": ["What is your brand voice?"]
}
```

--------------------------------

### Start a job via MCP tool

Source: https://shapelessai.com/docs/jobs

Calls the jobs_create MCP tool with a goal and budget. Requires the write permission.

```jsonc
// MCP
{ "tool": "jobs_create", "arguments": { "goal": "Draft three posts about our beta launch", "budgetUsd": 2.5 } }
```

--------------------------------

### Example platform rules JSON response

Source: https://shapelessai.com/docs/platforms

Example JSON response from the API showing the structure of a platform entry, including text limits, media rules, first-comment support, and settings schema. The settingsSchema is plain JSON Schema that MCP hosts and OpenAPI readers can use.

```jsonc
{
  "platforms": [
    {
      "id": "linkedin",
      "label": "LinkedIn",
      "oauth": true,          // connectable through the platform's own sign-in today
      "live": true,           // publishing works end to end; false = built, waiting on the platform
      "waitingOn": null,      // why it is not live, when it is not
      "text": { "maxChars": 3000 },
      "media": {
        "maxChars": 3000, "maxImages": 20, "minImages": 0,
        "allowsPdf": true, "maxVideos": 1, "requiresVideo": false, "imagesOrVideoOnly": true
      },
      "titleRequired": false, // true = documentTitle is required (YouTube)
      "firstComment": { "supported": true, "maxChars": 1250 },
      "settingsSchema": { "type": "object", "properties": {}, "additionalProperties": false },
      "connectPath": "/studio/accounts"
    }
  ]
}
```

--------------------------------

### GET /api/studio/tail

Source: https://shapelessai.com/docs/api

Tails studio logs.

```APIDOC
## GET /api/studio/tail

### Description
Tails studio logs.

### Method
GET

### Endpoint
/api/studio/tail

```

--------------------------------

### GET /api/media/{key}

Source: https://shapelessai.com/docs/api

Retrieves media by key.

```APIDOC
## GET /api/media/{key}

### Description
Retrieves media by key.

### Method
GET

### Endpoint
/api/media/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - The key of the media.

```

--------------------------------

### POST /api/studio

Source: https://shapelessai.com/docs/api.md

Starts one agent turn and returns an NDJSON stream of StudioEvents.

```APIDOC
## POST /api/studio

### Description
Starts one agent turn and returns an NDJSON stream of StudioEvents.

### Method
POST

### Endpoint
/api/studio

### Scope
write
```

--------------------------------

### GET /api/capabilities

Source: https://shapelessai.com/docs/api

Returns everything Shapeless can do, live or planned, as JSON.

```APIDOC
## GET /api/capabilities

### Description
Returns everything Shapeless can do, live or planned, as JSON.

### Method
GET

### Endpoint
/api/capabilities

### Scope
none

### Response
#### Success Response (200)
- **capabilities** (array) - List of capabilities.

#### Response Example
{
  "capabilities": [
    { "id": "cap_1", "name": "Schedule posts", "status": "live" }
  ]
}
```

--------------------------------

### Shapeless CLI: connections, platforms, capabilities, tools, and posts create

Source: https://shapelessai.com/docs/cli

Shows the main CLI commands for listing connections, linking accounts, viewing platform limits, capabilities, and tools, running a tool, and creating posts with various options. The post flags map one-to-one onto the POST /api/posts body: --to is connectionId, --text is postText, --at is scheduledAt, --queue is queue, --media is mediaKeys, --title is documentTitle, --settings is settings, and --first-comment is firstComment. --at and --queue are exclusive. Requires a key with publish permission. On the Free plan, the eleventh post in a UTC day returns 402 free_daily_cap.

```bash
shapeless connections                      # the connected accounts and their ids
shapeless connections link linkedin        # the URL a human opens to connect one  [write]
shapeless platforms                        # limits and rules, no key needed
shapeless capabilities                     # everything Shapeless can do, live or planned
shapeless tools                            # every agent tool on its own, with prices
shapeless tools run generate_image --input '{"name":"desk","prompt":"...","aspectRatio":"4:5"}'  [write]
shapeless capabilities want video-editing  # tell me when it ships

shapeless posts create --to <connectionId> --text "Shipped the thing."
shapeless posts create --to <connectionId> --text "..." --at 2026-09-22T07:00:00Z
shapeless posts create --to <connectionId> --text "..." --queue
shapeless posts create --to <connectionId> --text "..." \
  --media workspace-assets/<account>/carousel.pdf --title "Ten lessons" \
  --first-comment "Full write-up: https://..."
shapeless posts create --to <connectionId> --text "..." --settings '{"subreddit":"startups","title":"..."}'
shapeless posts create --to <youtubeConnectionId> --text "..." --media <clip.mp4 key> \
  --title "The video title" --settings '{"privacyStatus":"unlisted"}'
```

--------------------------------

### Shapeless posts create command examples

Source: https://shapelessai.com/docs/cli.md

Create posts with various options: basic text, scheduled time, queueing, media attachments, platform-specific settings, and YouTube-specific settings. Requires a key with 'publish' permission. The --at and --queue flags are mutually exclusive.

```bash
shapeless posts create --to <connectionId> --text "Shipped the thing."
shapeless posts create --to <connectionId> --text "..." --at 2026-09-22T07:00:00Z
shapeless posts create --to <connectionId> --text "..." --queue
shapeless posts create --to <connectionId> --text "..." \
  --media workspace-assets/<account>/carousel.pdf --title "Ten lessons" \
  --first-comment "Full write-up: https://..."
shapeless posts create --to <connectionId> --text "..." --settings '{"subreddit":"startups","title":"..."}'
shapeless posts create --to <youtubeConnectionId> --text "..." --media <clip.mp4 key> \
  --title "The video title" --settings '{"privacyStatus":"unlisted"}'
```

--------------------------------

### GET /api/assets

Source: https://shapelessai.com/docs/brand-memory.md

Alias for GET /api/brain/assets, returns the whole asset library.

```APIDOC
## GET /api/assets

### Description
Alias for GET /api/brain/assets, returns the whole asset library.

### Method
GET

### Endpoint
/api/assets

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token with `read` scope.

### Response
#### Success Response (200)
- **assets** (array) - List of asset objects.

#### Response Example
```json
{
  "assets": [
    { "filename": "logo.png", "mediaKey": "..." }
  ]
}
```
```

--------------------------------

### GET /api/capabilities

Source: https://shapelessai.com/docs/index.md

Lists the capabilities of the platform to determine what content can be created.

```APIDOC
## GET /api/capabilities

### Description
Lists the capabilities of the platform to determine what content can be created.

### Method
GET

### Endpoint
/api/capabilities

### Response
#### Success Response (200)
- **capabilities** (array) - List of available capabilities.

#### Response Example
{
  "capabilities": ["social_media_posts"]
}
```

--------------------------------

### Publish now with CLI

Source: https://shapelessai.com/docs/posts

CLI equivalent for publishing immediately using the shapeless posts create command.

```bash
shapeless posts create --to c_123 --text "Shipped."
```

--------------------------------

### GET /api/tools

Source: https://shapelessai.com/docs/api.md

Lists all available tools with their JSON Schema input and default price. No API key required.

```APIDOC
## GET /api/tools

### Description
Lists the catalog of all tools the studio agent holds, each with its JSON Schema input and default price. No API key is required.

### Method
GET

### Endpoint
/api/tools

### Response
#### Success Response (200)
- **tools** (array) - List of tool objects.
  - **name** (string) - Tool name.
  - **description** (string) - Tool description.
  - **inputSchema** (object) - JSON Schema for the tool input.
  - **costUsd** (number) - Default price in USD.

#### Response Example
{
  "tools": [
    {
      "name": "generate_image",
      "description": "Generate an image from a prompt",
      "inputSchema": {},
      "costUsd": 0.05
    }
  ]
}
```

--------------------------------

### Example onboarding API response

Source: https://shapelessai.com/docs/brand-memory

Shows the JSON structure returned by the onboarding endpoint, including completion percentage, open items with questions and hints, and a 'how' field describing the required workflow.

```jsonc
{
  "percent": 41,
  "open": [
    { "path": "voice.md", "question": "How do you sound?", "gainPercent": 18,
      "questions": [ { "level": 1, "question": "How do you sound?", "hint": "Three words..." } ] }
  ],
  "done": false,
  "how": "For each open item: ask the human its questions, write the answers as markdown under the question headings, PUT /api/workspace/file {path, content}, then GET this again until open is empty."
}
```

--------------------------------

### GET /api/manager/settings

Source: https://shapelessai.com/docs/api.md

Retrieves cadence and targeting settings. Requires read scope.

```APIDOC
## GET /api/manager/settings

### Description
Retrieves cadence and targeting settings.

### Method
GET

### Endpoint
/api/manager/settings

### Parameters
#### Query Parameters
- **scope** (string) - Required - Must be `read`.

### Response
#### Success Response (200)
- **settings** (object) - Manager settings.

#### Response Example
{
  "settings": {}
}
```

--------------------------------

### Start local MCP server with shapeless mcp

Source: https://shapelessai.com/docs/cli

Runs the local MCP server on stdio using the key from `shapeless login`. Adds tools that read your disk: `assets_upload`, `brain_import`, and `files` on a job message. These tools only read paths that resolve inside the server's working directory or a directory in `SHAPELESS_UPLOAD_ROOT`, with no hidden segment, and within upload size caps. Set `SHAPELESS_UPLOAD_ROOT` in the server's env to allow access.

```bash
shapeless mcp
```

--------------------------------

### Sign up without a browser

Source: https://shapelessai.com/docs/auth.md

Create an account and mint an API key in four calls. The email OTP code lasts 10 minutes and dies after 3 wrong tries. The key is returned once in the response.

```bash
EMAIL=founder@example.com
curl -X POST https://shapelessai.com/api/auth/email-otp/send-verification-otp \
  -H 'content-type: application/json' -d "{\"email\":\"$EMAIL\",\"type\":\"sign-in\"}"
# read the code from the mail "<code> is your ShapelessAI sign-in code"
curl -c jar -X POST https://shapelessai.com/api/auth/sign-in/email-otp \
  -H 'content-type: application/json' -d "{\"email\":\"$EMAIL\",\"otp\":\"123456\"}"
curl -b jar -X POST https://shapelessai.com/api/keys \
  -H 'content-type: application/json' -d '{"name":"my agent","scopes":["read","write","publish"]}'
# answers {"plaintext":"slk_..."} once; keep it, then drop the cookie jar
```

--------------------------------

### GET /api/identities

Source: https://shapelessai.com/docs/api

Retrieves identities.

```APIDOC
## GET /api/identities

### Description
Retrieves identities.

### Method
GET

### Endpoint
/api/identities

```

--------------------------------

### GET /api/influencers

Source: https://shapelessai.com/docs/api

Retrieves influencers.

```APIDOC
## GET /api/influencers

### Description
Retrieves influencers.

### Method
GET

### Endpoint
/api/influencers

```

--------------------------------

### List and upload assets with shapeless CLI

Source: https://shapelessai.com/docs/brand-memory

Shows CLI commands to list assets and upload a new asset, with the upload printing the media key.

```bash
shapeless assets list
shapeless assets upload ./logo.png     # prints the media key
```

--------------------------------

### Query workspace onboarding with curl

Source: https://shapelessai.com/docs/brand-memory

Fetches the onboarding status and open questions from the workspace onboarding API. Requires an API key in the SHAPELESS_API_KEY environment variable. The response includes open items with questions and hints, and a 'how' field describing the workflow.

```bash
curl -s https://shapelessai.com/api/workspace/onboarding -H "Authorization: Bearer $SHAPELESS_API_KEY"
```

--------------------------------

### GET /api/trends

Source: https://shapelessai.com/docs/api

Retrieves trends.

```APIDOC
## GET /api/trends

### Description
Retrieves trends.

### Method
GET

### Endpoint
/api/trends

```

--------------------------------

### Call brain_onboarding MCP tool

Source: https://shapelessai.com/docs/brand-memory

Example JSON-RPC request for the MCP tool 'brain_onboarding' with empty arguments, used to trigger onboarding from an MCP client.

```jsonc
// MCP
{ "tool": "brain_onboarding", "arguments": {} }
```

--------------------------------

### GET /api/metrics

Source: https://shapelessai.com/docs/api

Retrieves metrics.

```APIDOC
## GET /api/metrics

### Description
Retrieves metrics.

### Method
GET

### Endpoint
/api/metrics

```

--------------------------------

### POST /api/v1/jobs

Source: https://shapelessai.com/docs/api.md

Starts a new job by sending a goal. Returns a 202 with the job's id and status.

```APIDOC
## POST /api/v1/jobs

### Description
Starts a new job with a goal. The server mints the job id and returns it immediately.

### Method
POST

### Endpoint
/api/v1/jobs

### Parameters
#### Request Body
- **goal** (string) - Required - The goal for the job.
- **label** (string) - Optional - Title for the job; defaults to first line of goal.
- **budgetUsd** (number) - Optional - Budget in USD.
- **timezone** (string) - Optional - Timezone for scheduling.
- **attachments** (array) - Optional - List of attachments, each with name and either text or mediaKey.
- **characters** (string) - Optional - Character settings.

### Request Example
{
  "goal": "Write a blog post about AI",
  "label": "Blog Post",
  "budgetUsd": 10,
  "timezone": "America/New_York",
  "attachments": [
    { "name": "notes.md", "text": "Launch is Thursday." }
  ]
}

### Response
#### Success Response (202)
- **id** (string) - The job id.
- **title** (string) - The job title.
- **status** (string) - The job status.

#### Response Example
{
  "id": "job_123",
  "title": "Blog Post",
  "status": "queued"
}
```

--------------------------------

### GET /api/profile/audits

Source: https://shapelessai.com/docs/api

Retrieves profile audits.

```APIDOC
## GET /api/profile/audits

### Description
Retrieves profile audits.

### Method
GET

### Endpoint
/api/profile/audits

```

--------------------------------

### Start a job with the shapeless CLI

Source: https://shapelessai.com/docs/jobs

Uses the shapeless CLI to create a job with a goal, label, and budget, and watches the run. Requires the write permission.

```bash
shapeless jobs create draft three posts about our beta launch --label "Beta launch" --budget 2.50 --watch
```

--------------------------------

### GET /api/openapi.json

Source: https://shapelessai.com/docs/api.md

Returns the OpenAPI 3.1 specification for every key-accepting route. No authentication required.

```APIDOC
## GET /api/openapi.json

### Description
Returns the OpenAPI 3.1 specification for every key-accepting route. No authentication required.

### Method
GET

### Endpoint
/api/openapi.json

### Request Example
```bash
curl -s https://shapelessai.com/api/openapi.json
```

### Response
#### Success Response (200)
- Returns the OpenAPI 3.1 specification in JSON format.

#### Response Example
(No explicit response schema provided in source.)
```

--------------------------------

### GET /api/metrics/followers

Source: https://shapelessai.com/docs/api

Retrieves follower metrics.

```APIDOC
## GET /api/metrics/followers

### Description
Retrieves follower metrics.

### Method
GET

### Endpoint
/api/metrics/followers

```

--------------------------------

### Manage proposed posts with shapeless CLI

Source: https://shapelessai.com/docs/posts

Use these commands to list proposed posts, approve them (moving to scheduled and counting against the Free day), dismiss them, or publish them immediately. Approving counts against the Free day the post lands on, just like creating one.

```bash
shapeless posts list --status proposed
shapeless posts approve <id>      # proposed -> scheduled   [publish]
shapeless posts dismiss <id>
shapeless posts publish <id>      # out, now                [publish]
```

--------------------------------

### GET /api/metrics/history

Source: https://shapelessai.com/docs/api

Retrieves metric history.

```APIDOC
## GET /api/metrics/history

### Description
Retrieves metric history.

### Method
GET

### Endpoint
/api/metrics/history

```

--------------------------------

### PUT /api/workspace/file

Source: https://shapelessai.com/docs/index.md

Writes answers to onboarding questions.

```APIDOC
## PUT /api/workspace/file

### Description
Writes answers to onboarding questions.

### Method
PUT

### Endpoint
/api/workspace/file

### Parameters
#### Request Body
- **answers** (object) - Required - The answers to the onboarding questions.

### Request Example
{
  "answers": {
    "brandVoice": "Professional"
  }
}

### Response
#### Success Response (200)
- **status** (string) - Confirmation status.

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### GET /api/brain/assets

Source: https://shapelessai.com/docs/api

Retrieves brain assets.

```APIDOC
## GET /api/brain/assets

### Description
Retrieves brain assets.

### Method
GET

### Endpoint
/api/brain/assets

```

--------------------------------

### tools_list

Source: https://shapelessai.com/docs/mcp.md

Returns the live catalog of the studio tools, each with its input schema and default price.

```APIDOC
## Tool: tools_list

### Description
Returns the live catalog of the studio tools, each with its input schema and default price.

### Scope
`read`

### Behavior
- Read-only, runs freely.
```

--------------------------------

### GET /api/workspace/export

Source: https://shapelessai.com/docs/api

Exports workspace data.

```APIDOC
## GET /api/workspace/export

### Description
Exports workspace data.

### Method
GET

### Endpoint
/api/workspace/export

```

--------------------------------

### GET /api/ai-tools

Source: https://shapelessai.com/docs/ai-tools

Retrieves every live listing in the directory as JSON. Each read counts as an 'agent read' on the returned rows.

```APIDOC
## GET /api/ai-tools

### Description
Retrieves every live listing in the directory as JSON. Each read counts as an 'agent read' on the returned rows.

### Method
GET

### Endpoint
/api/ai-tools

### Response
#### Success Response (200)
- **listings** (array) - Array of live tool listings.

#### Response Example
{
  "listings": []
}
```

--------------------------------

### GET /api/media/[...key]

Source: https://shapelessai.com/docs/brand-memory

Streams any media key this account owns. Requires read scope.

```APIDOC
## GET /api/media/[...key]

### Description
Streams any media key this account owns. Requires read scope.

### Method
GET

### Endpoint
/api/media/[...key]

### Path Parameters
- **key** (string) - Required - The media key to stream.

### Scope
read

### Response
#### Success Response (200)
Streams the media content.
```

--------------------------------

### GET /api/capabilities

Source: https://shapelessai.com/docs

Lists all capabilities, live or planned. Planned routes return 501 with the shape they will take.

```APIDOC
## GET /api/capabilities

### Description
Lists all capabilities, live or planned. Planned routes return 501 with the shape they will take.

### Method
GET

### Endpoint
/api/capabilities

### Response
#### Success Response (200)
- **capabilities** (array) - List of capabilities.

#### Response Example
{
  "capabilities": [
    {
      "name": "post",
      "status": "live"
    },
    {
      "name": "future_feature",
      "status": "planned"
    }
  ]
}
```

--------------------------------

### GET /api/workspace

Source: https://shapelessai.com/docs/api

Retrieves workspace information.

```APIDOC
## GET /api/workspace

### Description
Retrieves workspace information.

### Method
GET

### Endpoint
/api/workspace

```

--------------------------------

### GET /api/characters

Source: https://shapelessai.com/docs/api

Retrieves a list of characters.

```APIDOC
## GET /api/characters

### Description
Retrieves a list of characters.

### Method
GET

### Endpoint
/api/characters

```

--------------------------------

### POST /api/videos/demo

Source: https://shapelessai.com/docs/api.md

Creates a recorded product demo of a page using the demo_page tool. Requires write scope.

```APIDOC
## POST /api/videos/demo

### Description
Creates a recorded product demo of a page using the `demo_page` tool.

### Method
POST

### Endpoint
/api/videos/demo

### Parameters
#### Request Body
- **url** (string) - Required - The URL of the page to demo.
- Additional fields as defined by the tool's input schema.

### Request Example
{
  "url": "https://example.com/product"
}

### Response
#### Success Response (200)
- **tool** (string) - Tool name.
- **output** (object) - Tool output.
- **media** (array) - List of media objects.
  - **key** (string) - Media key.
  - **url** (string) - Media URL.
- **chargedUsd** (number) - Actual cost charged.

#### Response Example
{
  "tool": "demo_page",
  "output": {},
  "media": [
    {
      "key": "demo_123",
      "url": "https://example.com/media/demo_123.mp4"
    }
  ],
  "chargedUsd": 0.15
}
```

--------------------------------

### brain_onboarding

Source: https://shapelessai.com/docs/mcp.md

Returns what is still open in Brand Memory, as questions with hints; answer with `brain_write`.

```APIDOC
## Tool: brain_onboarding

### Description
Returns what is still open in Brand Memory, as questions with hints; answer with `brain_write`.

### Scope
`read`

### Behavior
- Read-only, runs freely.
```

--------------------------------

### GET /api/manager/settings

Source: https://shapelessai.com/docs/api

Retrieves manager settings.

```APIDOC
## GET /api/manager/settings

### Description
Retrieves manager settings.

### Method
GET

### Endpoint
/api/manager/settings

```

--------------------------------

### POST /api/v1/jobs

Source: https://shapelessai.com/docs/jobs

Starts a new durable job by submitting a goal. Returns a 202 with the job id and status. Requires write permission.

```APIDOC
## POST /api/v1/jobs

### Description
Starts a new durable job by submitting a goal. The agent team researches, writes, designs, and renders content asynchronously, leaving the result in the queue for approval.

### Method
POST

### Endpoint
https://shapelessai.com/api/v1/jobs

### Parameters
#### Request Body
- **goal** (string) - Required - The goal for the job, e.g., "Draft three posts about our beta launch".
- **label** (string) - Optional - Becomes the title of the job; if omitted, the goal's first line is used.
- **budgetUsd** (number) - Optional - Caps what the run may spend.
- **timezone** (string) - Optional - Tells the agent what "tomorrow morning" means.

### Request Example
{
  "goal": "Draft three posts about our beta launch",
  "label": "Beta launch",
  "budgetUsd": 2.5
}

### Response
#### Success Response (202)
- **id** (string) - The job id, e.g., "j_123".
- **title** (string) - The job title, e.g., "Beta launch".
- **status** (string) - The job status, e.g., "running".

#### Response Example
{
  "id": "j_123",
  "title": "Beta launch",
  "status": "running"
}

### Authentication
Requires Authorization header with Bearer token (SHAPELESS_API_KEY).

### Permissions
Requires write permission.
```

--------------------------------

### GET /api/strategies

Source: https://shapelessai.com/docs/api

Retrieves a list of strategies.

```APIDOC
## GET /api/strategies

### Description
Retrieves a list of strategies.

### Method
GET

### Endpoint
/api/strategies

```

--------------------------------

### Run onboarding via shapeless CLI

Source: https://shapelessai.com/docs/brand-memory

Invokes the 'brain onboarding' command in the shapeless CLI to interactively complete the onboarding process.

```bash
shapeless brain onboarding
```

--------------------------------

### Start a job with curl

Source: https://shapelessai.com/docs/jobs

Sends a POST request to /api/v1/jobs with a goal, label, and budget. Requires the write permission. Returns a 202 with the job id and status.

```bash
curl -s https://shapelessai.com/api/v1/jobs \
  -H "Authorization: Bearer $SHAPELESS_API_KEY" -H "Content-Type: application/json" \
  -d '{"goal":"Draft three posts about our beta launch","label":"Beta launch","budgetUsd":2.5}'
# 202 {"id":"j_123","title":"Beta launch","status":"running"}
```

--------------------------------

### GET /api/posts/cap

Source: https://shapelessai.com/docs/api

Retrieves the cap for posts.

```APIDOC
## GET /api/posts/cap

### Description
Retrieves the cap for posts.

### Method
GET

### Endpoint
/api/posts/cap

```

--------------------------------

### CLI: Upload asset and create post with media

Source: https://shapelessai.com/docs/posts

Two bash commands: first uploads a PDF asset and prints the media key, second creates a LinkedIn post using that media key. The media key must be owned by the account; otherwise a 400 error is returned. The file extension determines the media kind: .pdf is a document, video extensions are video, everything else is an image.

```bash
shapeless assets upload ./carousel.pdf     # prints the media key
shapeless posts create --to c_linkedin --text "Ten lessons." \
  --media workspace-assets/<account>/carousel.pdf --title "Ten lessons from a year of shipping"
```

--------------------------------

### GET /api/posts

Source: https://shapelessai.com/docs/api

Retrieves a list of posts.

```APIDOC
## GET /api/posts

### Description
Retrieves a list of posts.

### Method
GET

### Endpoint
/api/posts

```

--------------------------------

### GET /api/connections

Source: https://shapelessai.com/docs/api

Retrieves a list of connections.

```APIDOC
## GET /api/connections

### Description
Retrieves a list of connections.

### Method
GET

### Endpoint
/api/connections

```

--------------------------------

### GET /api/tools

Source: https://shapelessai.com/docs/api

Retrieves a list of tools.

```APIDOC
## GET /api/tools

### Description
Retrieves a list of tools.

### Method
GET

### Endpoint
/api/tools

```

--------------------------------

### Post with CLI

Source: https://shapelessai.com/docs

Creates a post using the Shapeless CLI. Requires a connection ID and API key.

```bash
shapeless posts create --to <connectionId> --text "Shipped the thing." --queue

```

--------------------------------

### GET /api/groups

Source: https://shapelessai.com/docs/api.md

Lists account groups.

```APIDOC
## GET /api/groups

### Description
Lists account groups.

### Method
GET

### Endpoint
/api/groups

### Scope
read
```

--------------------------------

### Job management commands

Source: https://shapelessai.com/docs/cli

Commands to create, list, show, tail, continue, and stop jobs. The create command accepts a prompt, optional --label, --budget, --watch, and --attach flags. The list command returns the 200 newest jobs and prints a cursor if older jobs exist, which can be used with --before. Continue can add media via --media-key.

```bash
shapeless jobs create draft three posts about our beta launch
shapeless jobs create plan this week --label "Weekly plan" --budget 2.50 --watch
shapeless jobs list                       # 200 newest; prints a cursor if older jobs exist
shapeless jobs list --before <cursor>
shapeless jobs show <id>
shapeless jobs tail <id>
shapeless jobs continue <id> keep going, but make the second post shorter --watch
shapeless jobs stop <id>

shapeless jobs create does this thumbnail work? --attach ./thumb.png --attach ./notes.md
shapeless jobs continue <id> and this one --media-key workspace-assets/<account>/logo.png
```

--------------------------------

### POST /api/manager/run

Source: https://shapelessai.com/docs/api.md

Plans now through the first active agent. Requires publish scope.

```APIDOC
## POST /api/manager/run

### Description
Plans now through the first active agent.

### Method
POST

### Endpoint
/api/manager/run

### Parameters
#### Query Parameters
- **scope** (string) - Required - Must be `publish`.

### Response
#### Success Response (200)
- **run** (object) - The run details.

#### Response Example
{
  "run": {}
}
```

--------------------------------

### Schedule a post with CLI

Source: https://shapelessai.com/docs/posts

CLI equivalent for scheduling a post with the --at flag.

```bash
shapeless posts create --to c_123 --text "Tuesday thought." --at 2026-09-22T07:00:00Z
```

--------------------------------

### agents_wake

Source: https://shapelessai.com/docs/mcp.md

PUBLISHES. Run an agent now.

```APIDOC
## Tool: agents_wake

### Description
PUBLISHES. Run an agent now.

### Scope
`publish`

### Behavior
- **PUBLISHES** - destructive annotation, host asks the human first.
```

--------------------------------

### GET /api/ads/performance

Source: https://shapelessai.com/docs/api

Retrieves ad performance data.

```APIDOC
## GET /api/ads/performance

### Description
Retrieves ad performance data.

### Method
GET

### Endpoint
/api/ads/performance

```

--------------------------------

### GET /api/ad-accounts

Source: https://shapelessai.com/docs/api

Retrieves a list of ad accounts.

```APIDOC
## GET /api/ad-accounts

### Description
Retrieves a list of ad accounts.

### Method
GET

### Endpoint
/api/ad-accounts

```

--------------------------------

### POST /api/strategies/[id]/run

Source: https://shapelessai.com/docs/api.md

Wakes an agent now. Requires publish scope.

```APIDOC
## POST /api/strategies/[id]/run

### Description
Wakes an agent now.

### Method
POST

### Endpoint
/api/strategies/[id]/run

### Parameters
#### Path Parameters
- **id** (string) - Required - Agent ID.

#### Query Parameters
- **scope** (string) - Required - Must be `publish`.

### Response
#### Success Response (200)
- **run** (object) - The run details.

#### Response Example
{
  "run": {}
}
```

--------------------------------

### Shapeless CLI commands for characters, brain, agents, and assets

Source: https://shapelessai.com/docs/cli

Commands to list characters, create a voice with description (spends credit), clone a voice with consent, manage brain memory (list, get, put, import, export), list agents, wake an agent, and manage assets.

```bash
shapeless characters list
shapeless characters voice maya --describe "warm documentary narrator, mid-40s, slight gravel"   # SPENDS CREDIT
shapeless characters voice maya --clone workspace-assets/<account>/take.weba --consent

shapeless brain ls
shapeless brain onboarding                 # what is still open, as questions to answer
shapeless brain get positioning.md
shapeless brain put voice.md --file ./voice.md
shapeless brain import ./pitch-deck.pdf
shapeless brain export --out brain.zip

shapeless agents list
shapeless agents wake <id>                # [publish]

shapeless assets list
shapeless assets upload ./logo.png
```

--------------------------------

### GET /api/manager/runs

Source: https://shapelessai.com/docs/api

Retrieves a list of manager runs.

```APIDOC
## GET /api/manager/runs

### Description
Retrieves a list of manager runs.

### Method
GET

### Endpoint
/api/manager/runs

```

--------------------------------

### GET /api/conversations/{id}

Source: https://shapelessai.com/docs/api

Retrieves a specific conversation.

```APIDOC
## GET /api/conversations/{id}

### Description
Retrieves a specific conversation.

### Method
GET

### Endpoint
/api/conversations/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the conversation.

```

--------------------------------

### capabilities_want

Source: https://shapelessai.com/docs/mcp.md

Ask to be told when a planned capability ships. Ask the human first.

```APIDOC
## Tool: capabilities_want

### Description
Ask to be told when a planned capability ships. Ask the human first.

### Scope
any

### Behavior
- Requires any scope.
- Must ask the human first.
```

--------------------------------

### GET /api/v1/jobs/{id}

Source: https://shapelessai.com/docs/api

Retrieves a specific job.

```APIDOC
## GET /api/v1/jobs/{id}

### Description
Retrieves a specific job.

### Method
GET

### Endpoint
/api/v1/jobs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the job.

```

--------------------------------

### Publish now with curl and CLI

Source: https://shapelessai.com/docs/posts.md

Publishes a post immediately by omitting scheduledAt or sending a past date. The curl example shows the response with the live URL. The CLI command uses 'shapeless posts create'.

```bash
curl -s https://shapelessai.com/api/posts \
  -H "Authorization: Bearer $SHAPELESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connectionId":"c_123","postText":"Shipped."}'
# {"id":"p_456","status":"published","publishedLocation":"https://www.linkedin.com/feed/update/..."}
```

```bash
shapeless posts create --to c_123 --text "Shipped."
```

--------------------------------

### GET /api/ai-tools/stats

Source: https://shapelessai.com/docs/api

Retrieves statistics for AI tools.

```APIDOC
## GET /api/ai-tools/stats

### Description
Retrieves statistics for AI tools.

### Method
GET

### Endpoint
/api/ai-tools/stats

```

--------------------------------

### GET /api/ai-tools

Source: https://shapelessai.com/docs/api

Retrieves a list of AI tools.

```APIDOC
## GET /api/ai-tools

### Description
Retrieves a list of AI tools.

### Method
GET

### Endpoint
/api/ai-tools

```

--------------------------------

### shapeless brain onboarding

Source: https://shapelessai.com/docs/cli.md

Shows what is still open in brand memory as questions to answer.

```APIDOC
## shapeless brain onboarding

### Description
Shows what is still open in brand memory as questions to answer.

### Method
CLI command

### Endpoint
`shapeless brain onboarding`

### Request Example
```bash
shapeless brain onboarding
```

### Response
#### Success Response
- List of open questions.

#### Response Example
```
(no explicit response format provided)
```
```

--------------------------------

### GET /api/platforms

Source: https://shapelessai.com/docs/api

Retrieves a list of supported platforms.

```APIDOC
## GET /api/platforms

### Description
Retrieves a list of supported platforms.

### Method
GET

### Endpoint
/api/platforms

```

--------------------------------

### GET /api/wiki/identity

Source: https://shapelessai.com/docs/api

Retrieves identity information from the wiki.

```APIDOC
## GET /api/wiki/identity

### Description
Retrieves identity information from the wiki.

### Method
GET

### Endpoint
/api/wiki/identity

```

--------------------------------

### GET /api/profile/audits/{connectionId}

Source: https://shapelessai.com/docs/api

Retrieves audits for a specific connection.

```APIDOC
## GET /api/profile/audits/{connectionId}

### Description
Retrieves audits for a specific connection.

### Method
GET

### Endpoint
/api/profile/audits/{connectionId}

### Parameters
#### Path Parameters
- **connectionId** (string) - Required - The ID of the connection.

```

--------------------------------

### Shapeless CLI commands for connections, platforms, capabilities, and tools

Source: https://shapelessai.com/docs/cli.md

Use these commands to inspect connected accounts, link a LinkedIn account, view platform limits, list capabilities, and run agent tools. The 'link' and 'tools run' commands require write permissions.

```bash
shapeless connections                      # the connected accounts and their ids
shapeless connections link linkedin        # the URL a human opens to connect one  [write]
shapeless platforms                        # limits and rules, no key needed
shapeless capabilities                     # everything Shapeless can do, live or planned
shapeless tools                            # every agent tool on its own, with prices
shapeless tools run generate_image --input '{"name":"desk","prompt":"...","aspectRatio":"4:5"}'  [write]
shapeless capabilities want video-editing  # tell me when it ships
```

--------------------------------

### GET /api/brain/assets/{filename}

Source: https://shapelessai.com/docs/api

Retrieves a specific brain asset.

```APIDOC
## GET /api/brain/assets/{filename}

### Description
Retrieves a specific brain asset.

### Method
GET

### Endpoint
/api/brain/assets/{filename}

### Parameters
#### Path Parameters
- **filename** (string) - Required - The name of the asset file.

```

--------------------------------

### GET /api/manager/runs/{id}

Source: https://shapelessai.com/docs/api

Retrieves a specific manager run.

```APIDOC
## GET /api/manager/runs/{id}

### Description
Retrieves a specific manager run.

### Method
GET

### Endpoint
/api/manager/runs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the manager run.

```

--------------------------------

### GET /api/me/email

Source: https://shapelessai.com/docs/api

Retrieves the email address of the authenticated user.

```APIDOC
## GET /api/me/email

### Description
Retrieves the email address of the authenticated user.

### Method
GET

### Endpoint
/api/me/email

```

--------------------------------

### Queue a post with CLI

Source: https://shapelessai.com/docs/posts

Queues a post to take the next free slot on the connection's posting times. Sending both queue and scheduledAt returns a 400; a fully booked connection returns a 409.

```bash
shapeless posts create --to c_123 --text "Next one out." --queue
```

--------------------------------

### POST /api/tools/{name}

Source: https://shapelessai.com/docs/mcp.md

Each studio tool is exposed as an MCP tool and as an HTTP endpoint POST /api/tools/{name}. The endpoint takes the write scope and accepts a JSON Schema input. A call holds budgetUsd of credit (default 2, max 10) and settles at actual cost. The response format is {tool, output, media: [{key, url}], chargedUsd}.

```APIDOC
## POST /api/tools/{name}

### Description
Each studio tool is exposed as an MCP tool and as an HTTP endpoint POST /api/tools/{name}. The endpoint takes the write scope and accepts a JSON Schema input. A call holds budgetUsd of credit (default 2, max 10) and settles at actual cost. The response format is {tool, output, media: [{key, url}], chargedUsd}.

### Method
POST

### Endpoint
/api/tools/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the tool to invoke.

#### Request Body
- **budgetUsd** (number) - Optional - Credit to hold while the call runs. Default 2, max 10.
- Additional fields per the tool's JSON Schema.

### Response
#### Success Response (200)
- **tool** (string) - The name of the tool.
- **output** (object) - The tool's output.
- **media** (array) - List of files created, each with key and url.
- **chargedUsd** (number) - The actual cost charged.

#### Response Example
{
  "tool": "generate_image",
  "output": {},
  "media": [
    {
      "key": "file-key",
      "url": "https://example.com/file.png"
    }
  ],
  "chargedUsd": 0.016
}
```