ShapelessAI

https://shapelessai.com/docs
Admin
ShapelessAI is a social media API, CLI and MCP server that lets AI agents publish to eight networks...
Tokens:106,665
Snippets:746
Trust Score:5.4
Update:3 hours ago
Show doc for...
Tokens:
Raw
### 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?"]
}
```

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

### 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"
    }
  ]
}
```

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

### 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": "..." }
  ]
}
```
```

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

### 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."
```

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

### 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 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."
}
```

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

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

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

### GET /api/identities

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

Retrieves identities.

```APIDOC
## GET /api/identities

### Description
Retrieves identities.

### Method
GET

### Endpoint
/api/identities

```

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

### 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/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

```

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

### 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/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/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

```

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

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

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

### 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/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

```

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

### 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"}
```

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

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

```

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

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

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

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

```

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

### 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": {}
}
```

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

### 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.

```

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

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

```
Tokens:
Raw