### Onboarding response with open items and how instructions

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

Example response from the onboarding endpoint. Contains a percent completion, an open array with items to process, and a how field explaining the workflow: ask questions, write answers as markdown, PUT the file, and GET again until open is empty.

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

```

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

### Example platform configuration JSON

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

Example response from GET /api/platforms showing the structure for a platform. Includes fields like 'oauth', 'live', 'text', 'media', 'titleRequired', 'firstComment', 'settingsSchema', and 'connectPath'. The 'settingsSchema' is plain JSON Schema.

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

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

### Install

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

Install the shapelessai-ai-sdk package and its peer dependencies.

```APIDOC
## Install

### Description
Install the shapelessai-ai-sdk package and its peer dependencies.

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

### Requirements
- Node 18 or newer
- `ai` 6 or newer
- `zod` 3.25 or 4 (peer dependency)
```

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

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

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

A set of example commands for listing characters, cloning a voice (spending credit), managing brain data (list, get, put, import, export), waking agents, and uploading assets. Comments indicate actions like spending credit and publishing.

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

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

### Configure Shapeless MCP server in .vscode/mcp.json

Source: https://shapelessai.com/connect/vscode

Manual setup for VS Code: add this JSON to .vscode/mcp.json, then start the server from the MCP view. VS Code opens a browser tab for sign-in and authorization.

```json
{ "servers": { "shapeless": { "type": "http", "url": "https://shapelessai.com/mcp" } } }
```

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

### Install Gemini CLI extension from repo

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

Installs the ShapelessAI extension for Gemini CLI from the GitHub repository. Run this command in a terminal.

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

```

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

### Install ShapelessAI Claude Code plugin

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

Adds the ShapelessAI plugin marketplace and installs the plugin. After installation, run /mcp, pick shapeless, and authenticate via the MCP server.

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

```

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

### Use the tools

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

Use the shapelessaiTools factory to get all tools, or import individual tools.

```APIDOC
## Use the tools

### Description
Use the shapelessaiTools factory to get all tools, or import individual tools.

### Example
```javascript
import { generateText, isStepCount } from "ai";
import { shapelessaiTools } from "shapelessai-ai-sdk";

const { text } = await generateText({
  model: "openai/gpt-5-mini",
  prompt: 'Schedule "We just shipped dark mode" to my LinkedIn in the next free slot.',
  tools: shapelessaiTools(),
  stopWhen: isStepCount(5),
});
```

### Tools
- `listAccounts` - The connected accounts a post can go to, with the `connectionId` the other tools take. Call it first.
- `createPost` - A post on one account: the account's next free queue slot by default, a set time with `scheduledAt`, or right away with `publishNow`.
- `listPosts` - Recent posts with status, scheduled time, the live URL once published, and the error when one failed.

### Individual Exports
- `listAccounts()`
- `createPost()`
- `listPosts()`

### Factory Options
- `{ apiKey, baseURL, needsApproval }`
```

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

### Install Claude Code plugin for Shapeless

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

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

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

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

### Error response examples for 402 and 422

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

Worked examples of error responses. The 402 shows the free_daily_cap shape with limit, day, resetsAt, and upgrade links. The 422 examples show platform rule violations: too many images, missing video, images and video together, and unsupported first comment.

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

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

### Example prompts for Discord posts

Source: https://shapelessai.com/mcp/discord

These are example prompts you can give to the host in chat to create Discord posts. Drafts are queued for approval unless specified otherwise, and the host asks before publishing or spending.

```text
Post the release notes to our #announcements channel on Discord, with the new-feature screenshot.
```

```text
Write a short Discord post inviting the community to Thursday's office hours and schedule it for Wednesday 5pm.
```

```text
Every Monday, draft a Discord post for #updates with what shipped last week; I approve each one.
```

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

### Install shapelessai-ai-sdk and ai

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

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

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

```

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

### Install Gemini CLI extension

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

Installs the ShapelessAI extension for Gemini CLI from the repository. Run this command in your terminal.

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

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

### Install shapelessai-ai-sdk and ai

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

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

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

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

### GET /api/workspace/onboarding

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

Retrieves the open onboarding questions and hints. Requires read scope.

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

### Description
Retrieves what is still open in Brand Memory, as questions a human answers, with hints.

### Method
GET

### Endpoint
/api/workspace/onboarding

### Authentication
Bearer API key with read scope.

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

#### Response Example
{
  "questions": [
    {
      "question": "What is your target audience?",
      "hint": "Consider demographics and interests."
    }
  ]
}
```

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

### Example prompts for TikTok MCP

Source: https://shapelessai.com/mcp/tiktok

These are example prompts you can use with the TikTok MCP server. They cover creating videos, repurposing content, and managing the schedule.

```text
Script and render a 30-second TikTok about the bug we fixed today, hook in the first second, captions on.
```

```text
Turn our latest blog post into a TikTok: doc-narrator style, our actor, vertical, under 45 seconds.
```

```text
What is scheduled for TikTok this week? Move Thursday's video to Friday 6pm.
```

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

### Install shapeless CLI with npx or npm

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

Install the shapeless CLI either as a one-off command with npx or globally with npm. Requires Node 20 or newer.

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

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

### Install shapeless CLI and MCP server

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

Install the shapeless package either one-off with npx or globally with npm 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/connect/chatgpt/telegram

Starts a durable job from a goal, optionally with files attached.

```APIDOC
## jobs_create

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

### Runs
Drafts

### Parameters
- **goal** (string) - Required - The goal for the job.
- **files** (array) - Optional - Files to attach to the job.

### Response
- **job_id** (string) - The ID of the created job.
- **web_url** (string) - The web URL to poll or continue the job.
```

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

### jobs_create

Source: https://shapelessai.com/connect/chatgpt/facebook

Starts a durable job from a goal, optionally with files attached.

```APIDOC
## jobs_create

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

### Method
MCP Tool

### Endpoint
`jobs_create`

### Parameters
- **goal** (string) - Required - The goal for the job.
- **files** (array) - Optional - Files to attach to the job.

### Response
- **job_id** (string) - The ID of the created job.
- **web_url** (string) - The web URL to poll or continue the job.

### Response Example
{
  "job_id": "job_123",
  "web_url": "https://shapelessai.com/jobs/job_123"
}
```

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

### curl example: GET /api/connections

Source: https://shapelessai.com/capabilities/connected-accounts

Example curl command to list connected accounts. Uses an Authorization header with a Bearer token.

```bash
curl -s https://shapelessai.com/api/connections -H "Authorization: Bearer 
```

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

### Publish now with CLI

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

CLI equivalent for immediate publishing.

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

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

### Onboard workspace via API with curl

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

Use this curl command to start the onboarding process for a workspace. Requires a Shapeless API key stored in the SHAPELESS_API_KEY environment variable.

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

```

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

### Onboard workspace via CLI with shapeless brain onboarding

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

Use the Shapeless CLI command to start the onboarding process for a workspace.

```bash
shapeless brain onboarding

```

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

### Example API response for platforms

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

Shows the structure of the response from GET /api/platforms, including fields like id, label, oauth, live, waitingOn, text, media, and titleRequired. The response includes comments indicating that oauth true means connectable through the platform's own sign-in, and live false means built but waiting on the platform.

```json
{
  "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
```

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

### Publish immediately with CLI

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

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

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

```

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

### POST /api/studio

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

Starts a studio session. This endpoint likely initializes a new studio environment.

```APIDOC
## POST /api/studio

### Description
Starts a studio session. This endpoint likely initializes a new studio environment.

### Method
POST

### Endpoint
/api/studio

```

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

### shapeless brain onboarding

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

Shows open onboarding questions via CLI.

```APIDOC
## shapeless brain onboarding

### Description
Shows what is still open in Brand Memory as questions.

### Method
CLI

### Command
shapeless brain onboarding

### Authentication
Requires API key configured in the CLI.

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

#### Response Example
Q1: What is your target audience?
Q2: What is your unique value proposition?
```

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

### Onboard workspace via MCP tool brain_onboarding

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

Use the MCP tool brain_onboarding with empty arguments to start the onboarding process.

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

```

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

### GET /api/me

Source: https://shapelessai.com/capabilities/connected-accounts

Gets who am I: account, plan, credit balance. Requires read scope.

```APIDOC
## GET /api/me

### Description
Gets who am I: account, plan, credit balance. Requires read scope.

### Method
GET

### Endpoint
/api/me

### Authentication
Bearer API key with read scope.

### Response
#### Success Response (200)
- **account** (object) - Account details.
- **plan** (string) - The plan name.
- **credit_balance** (number) - The credit balance.
```

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

### GET /api/posts/cap

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

Retrieves the post cap. Use this endpoint to get the current cap on posts.

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

### Description
Retrieves the post cap.

### Method
GET

### Endpoint
/api/posts/cap

```

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

### POST /api/videos/demo

Source: https://shapelessai.com/capabilities/record-demo

Creates a demo video by sending a request with a name, URL, and steps. Requires an API key for authorization.

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

### Description
Creates a demo video by providing a name, URL, and steps. The request must include an Authorization header with a Bearer token.

### Method
POST

### Endpoint
https://shapelessai.com/api/videos/demo

### Parameters
#### Request Body
- **name** (string) - Required - The name of the demo.
- **url** (string) - Required - The URL to record.
- **steps** (string) - Required - The steps to perform, separated by semicolons.

### Request Example
```bash
curl -s https://shapelessai.com/api/videos/demo -H "Authorization: Bearer $SHAPELESS_API_KEY" -H "Content-Type: application/json" -d '{"name":"signup demo","url":"https://example.com","steps":"click Get started; type founder@example.com into Email; click Continue"}'
```

### Response
#### Success Response (200)
No response body details are provided in the source.

#### Error Responses
- **400** - The input does not match the tool's schema; the message names the field.
- **402** - Not enough credit to hold budgetUsd, or the call costs more than budgetUsd.
- **404** - No such tool on this deployment.
- **422** - The tool refused this input; nothing was charged.
- **502** - The tool failed; nothing was charged.

```

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

### reference_read

Source: https://shapelessai.com/capabilities/agent-tools

Read 1 to 3 exemplars from reference_search in full: why they worked, their structure and beats, the transcript and on-screen text, and the recipe to rebuild the format for another brand. Free to use, with a budget held during execution.

```APIDOC
## reference_read

### Description
Read 1 to 3 exemplars from reference_search in full: why they worked, their structure and beats, the transcript and on-screen text, and the recipe to rebuild the format for another brand. Free to use, with a budget held during execution.

### Method
Not specified

### Endpoint
Not specified

### Parameters
- **reference_ids** (array of strings) - Required - IDs of the references to read (1 to 3).
- **budgetUsd** (number) - Optional - Maximum budget in USD (default 2, max 10). Held while the tool runs and released after.

### Request Example
{
  "reference_ids": ["ref1", "ref2"],
  "budgetUsd": 2
}

### Response
#### Success Response
- **exemplars** (array) - Full details of each reference, including why they worked, structure, transcript, and recipe.

#### Response Example
{
  "exemplars": [
    {
      "id": "ref1",
      "why_it_worked": "Explanation",
      "structure": "Structure description",
      "transcript": "Full transcript",
      "recipe": "Recipe to rebuild"
    }
  ]
}
```

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

### GET · PUT /api/manager/settings

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

Retrieves or updates manager settings. This endpoint allows getting and setting configuration.

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

### Description
Retrieves or updates manager settings.

### Method
GET, PUT

### Endpoint
/api/manager/settings

```

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

### Example onboarding API response

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

Shows the JSON structure returned by the onboarding endpoint, including percent complete, open items, and instructions for the agent.

```json
{
  "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/brain/assets and GET /api/assets

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

Lists brand uploads and the entire asset library. Requires read scope.

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

### Description
Lists brand uploads and the whole asset library.

### Method
GET

### Endpoint
/api/brain/assets
/api/assets

### Parameters
#### Scope
- **read** (string) - Required - The scope required for this operation.

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

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

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

### GET /api/me

Source: https://shapelessai.com/capabilities/connected-accounts

Get information about the current user: account, plan, and credit balance. This endpoint requires read scope.

```APIDOC
## GET /api/me

### Description
Get information about the current user: account, plan, and credit balance. This endpoint requires read scope.

### Method
GET

### Endpoint
/api/me

### Response
#### Success Response (200)
No response body documented.

```

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

### Query workspace onboarding with curl

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

Use this curl command to fetch the current onboarding state, including open questions and progress. Requires a SHAPELESS_API_KEY environment variable.

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

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

### render_thumbnail

Source: https://shapelessai.com/capabilities/render-thumbnail

Packages a finished video with its cover: one frame of it (frame_at, in seconds), three to five words, at most one picture. Filed beside the video as <video>-thumbnail.jpg, so a post that carries the video key gets the cover. Free: budgetUsd (default 2, max 10) is held while it runs and released.

```APIDOC
## render_thumbnail

### Description
Packages a finished video with its cover: one frame of it (frame_at, in seconds), three to five words, at most one picture. Filed beside the video as <video>-thumbnail.jpg, so a post that carries the video key gets the cover. Free: budgetUsd (default 2, max 10) is held while it runs and released.

### Method
MCP Tool

### Endpoint
https://shapelessai.com/mcp

### Parameters
- **frame_at** (number) - Required - Time in seconds to select the frame for the thumbnail.
- **words** (string) - Required - Three to five words to place on the thumbnail.
- **picture** (string) - Optional - At most one picture to include on the thumbnail.
- **budgetUsd** (number) - Optional - Budget in USD, default 2, max 10. Held while the operation runs and released after.

### Response
#### Success Response
- **thumbnail_path** (string) - Path to the generated thumbnail file, saved as <video>-thumbnail.jpg.

#### Response Example
{
  "thumbnail_path": "<video>-thumbnail.jpg"
}
```

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

### Read and edit queue slots with curl GET and PATCH

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

Use curl to read the current queue slots with GET, and to update them with PATCH. The GET response shows the slots, timezone, and next scheduled time. The PATCH request updates the slots and timezone.

```bash
curl -s https://shapelessai.com/api/connections/c_123/queue -H "Authorization: Bearer $SHAPELESS_API_KEY"
# {"slots":["09:00","13:00","17:00"],"timezone":"UTC","next":"2026-09-15T09:00:00.000Z"}

curl -s -X PATCH https://shapelessai.com/api/connections/c_123/queue \
 -H "Authorization: Bearer $SHAPELESS_API_KEY" -H "Content-Type: application/json" \
 -d '{"slots":["08:30","16:00"],"timezone":"Europe/Berlin"}'

```

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

### reference_read

Source: https://shapelessai.com/capabilities/agent-tools

Reads 1 to 3 exemplars from reference_search in full: why they worked, their structure and beats, the transcript and on-screen text, and the recipe to rebuild the format for another brand. Free: budgetUsd (default 2, max 10) is held while it runs and released. Needs the write scope.

```APIDOC
## reference_read

### Description
Read 1 to 3 exemplars from reference_search in full: why they worked, their structure and beats, the transcript and on-screen text, and the recipe to rebuild the format for another brand. Free: budgetUsd (default 2, max 10) is held while it runs and released. Needs the write scope.

### Method
MCP Tool Call

### Parameters
- **exemplar_ids** (array of strings) - Required - 1 to 3 exemplar IDs from reference_search.
- **budgetUsd** (number) - Optional - Default 2, max 10. Budget cap for the operation.

### Notes
- Requires the write scope.
- Free: budgetUsd is held while it runs and released.
```

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

### GET /api/ai-tools/{slug}

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

Retrieves a single listing by its slug. Use this endpoint to get details for one specific AI tool.

```APIDOC
## GET /api/ai-tools/{slug}

### Description
Retrieves a single listing by its slug.

### Method
GET

### Endpoint
/api/ai-tools/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The unique identifier of the tool listing.

### Response
#### Success Response (200)
- **slug** (string) - The unique identifier.
- **name** (string) - The tool's name.
- **description** (string) - A description of the tool.

#### Response Example
{
  "slug": "example-tool",
  "name": "Example Tool",
  "description": "A description of the tool."
}
```

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

### GET /api/connections

Source: https://shapelessai.com/docs

Retrieves the list of social media connections. Use this to check which networks are connected and get the connect URL for any missing networks.

```APIDOC
## GET /api/connections

### Description
Retrieves the list of social media connections. Use this to check which networks are connected and get the connect URL for any missing networks.

### Method
GET

### Endpoint
/api/connections

### Response
#### Success Response (200)
- **connections** (array) - List of connection objects.
- **connect.url** (string) - URL to connect a missing network.

#### Response Example
{
  "connections": [
    {
      "network": "twitter",
      "connected": true,
      "connect": {
        "url": "https://shapelessai.com/connect/twitter"
      }
    }
  ]
}
```

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

### Create posts with shapeless posts create

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

These commands create posts with various options: immediate, scheduled, queued, with media, and with platform-specific settings. The --at and --queue flags are exclusive.

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

```bash
shapeless posts create --to <connectionId> --text "..." --at 2026-09-22T07:00:00Z
```

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

```bash
shapeless posts create --to <connectionId> --text "..." \
 --media workspace-assets/<account>/carousel.pdf --title "Ten lessons" \
 --first-comment "Full write-up: https://..."
```

```bash
shapeless posts create --to <connectionId> --text "..." --settings '{"subreddit":"startups","title":"..."}'
```

```bash
shapeless posts create --to <youtubeConnectionId> --text "..." --media <clip.mp4 key> \
 --title "The video title" --settings '{"privacyStatus":"unlisted"}'
```

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

### GET /api/me/email

Source: https://shapelessai.com/capabilities/connected-accounts

Gets whether lifecycle email (posts ready, weekly summary) is on, and the last emails we sent this account. Requires read scope.

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

### Description
Gets whether lifecycle email (posts ready, weekly summary) is on, and the last emails we sent this account. Requires read scope.

### Method
GET

### Endpoint
/api/me/email

### Authentication
Bearer API key with read scope.

### Response
#### Success Response (200)
- **lifecycle** (boolean) - Whether lifecycle email is on.
- **last_emails** (array) - List of last emails sent.
```

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

### GET /api/platforms

Source: https://shapelessai.com/capabilities/connected-accounts

Gets every platform the rail posts to: limits, media rules, settings schema, first-comment support. No API key required.

```APIDOC
## GET /api/platforms

### Description
Gets every platform the rail posts to: limits, media rules, settings schema, first-comment support. No API key required.

### Method
GET

### Endpoint
/api/platforms

### Authentication
None

### Response
#### Success Response (200)
- **platforms** (array) - List of platforms with their limits, media rules, settings schema, and first-comment support.
```

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

### Call brain_onboarding MCP tool

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

Invoke the brain_onboarding tool via MCP with an empty arguments object.

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

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

### List and upload assets with shapeless CLI

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

Use these commands to list existing assets and upload a new one. The upload prints the media key.

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

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

### Create a marketing job with shapeless jobs create

Source: https://shapelessai.com/

Use this command to create a new marketing job. The command includes a prompt describing the task and attaches a media file. The output confirms the job is queued.

```bash
$$ shapeless jobs create "cut this take into a short, everywhere, 9am" --attach ./take.mp4
```

```text
✓ queued · the team is on it
```

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

### Start a job with the CLI

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

Creates a job using the shapeless CLI with a goal, label, budget, and watch flag.

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

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

### Start a job via MCP

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

Invokes the jobs_create tool via MCP with a goal and budget.

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

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

### Run record demo via CLI

Source: https://shapelessai.com/capabilities/record-demo

Use the shapeless CLI to run the demo page. The command takes a JSON input string; use 'tools show demo_page' to print the schema.

```bash
shapeless tools run demo_page --input '<json>'
```

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

### GET /api/posts/cap

Source: https://shapelessai.com/capabilities/publish-post

Get the Free plan's daily post cap and how many posts are already scheduled for the UTC day of the specified timestamp. Requires the read scope.

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

### Description
Get the Free plan's daily post cap and how many posts are already scheduled for the UTC day of the specified timestamp. Requires the read scope.

### Method
GET

### Endpoint
/api/posts/cap

### Parameters
#### Query Parameters
- **at** (string) - Required - The timestamp to check the cap for.

### Request Example
No request body.

### Response
#### Success Response (200)
- **cap** (integer or null) - The daily cap for the Free plan, or null for paid plans.
- **count** (integer) - How many posts already go out on the UTC day ?at= falls on.

#### Response Example
{
  "cap": 5,
  "count": 2
}
```

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

### curl example for /api/videos/generate

Source: https://shapelessai.com/capabilities/generate-video

Sends a POST request to the video generation endpoint with an Authorization header and a JSON body containing name and prompt. The example uses the SHAPELESS_API_KEY environment variable.

```bash
curl -s https://shapelessai.com/api/videos/generate -H "Authorization: Bearer $SHAPELESS_API_KEY" -H "Content-Type: application/json" -d '{"name":"rain window","prompt":"Slow push-in on rain hitting a window at night, neon bleeding through."}'
```

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

### Start the local MCP server

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

Runs the Shapeless MCP server on stdio using the key from `shapeless login`. Adds disk-reading tools (`assets_upload`, `brain_import`, `files`) that the hosted server cannot have. Paths are only read when they resolve inside the working directory or `SHAPELESS_UPLOAD_ROOT`, with no hidden segment, and within upload size caps.

```bash
shapeless mcp
```

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

### Shapeless CLI: Connections, Platforms, Capabilities, and Tools

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

Commands to list connected accounts, get the URL to link a new account, view platform limits, list capabilities, and run agent tools. The `link` and `tools run` commands require write access.

```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 job status with shapeless CLI

Source: https://shapelessai.com/

Use the `shapeless jobs get` command to check the status of a job. The output shows the job details, including the cut, captions, thumbnail, and networks.

```bash
$ shapeless jobs get j_4d82
● 0:45 → 0:29 · cut on its words · captions · thumbnail · 12 networks · awaiting approve
```

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

### CLI: Create a post with shapeless

Source: https://shapelessai.com/free

Use this CLI command to create a post. Requires a connection ID and text. Use --queue to add to the queue, or --scheduled-at to schedule for a specific time.

```bash
shapeless posts create --to CONNECTION_ID --text "We rebuilt onboarding this week. Here is what broke first, and what we changed." --queue
```

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

### GET /api/connections/{id}/tiktok-creator-info

Source: https://shapelessai.com/capabilities/connected-accounts

Gets TikTok's creator info for that connection: privacy levels, limits. Requires read scope. Read it before every TikTok post; TikTok forbids caching it.

```APIDOC
## GET /api/connections/{id}/tiktok-creator-info

### Description
Gets TikTok's creator info for that connection: privacy levels, limits. Requires read scope. Read it before every TikTok post; TikTok forbids caching it.

### Method
GET

### Endpoint
/api/connections/{id}/tiktok-creator-info

### Authentication
Bearer API key with read scope.

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

### Response
#### Success Response (200)
- **privacy_levels** (array) - Available privacy levels.
- **limits** (object) - Posting limits.
```

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

### Example curl request for record demo

Source: https://shapelessai.com/capabilities/record-demo

Sends a POST request to the ShapelessAI API to run the record demo with a sample video name, URL, and steps. Requires the SHAPELESS_API_KEY environment variable.

```bash
curl -s https://shapelessai.com/api/videos/demo -H "Authorization: Bearer $SHAPELESS_API_KEY" -H "Content-Type: application/json" -d '{"name":"signup demo","url":"https://example.com","steps":"click Get started; type founder@example.com into Email; click Continue"}'
```

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

### brain_onboarding

Source: https://shapelessai.com/connect/chatgpt/bluesky

Provides what is still open in Brand Memory, as questions a human answers, with hints. Ask the human to complete these.

```APIDOC
## brain_onboarding

### Description
What is still open in Brand Memory, as the questions a human answers, with hints. Ask the human to complete these.

### Access
reads
```

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

### TikTok settings JSON example

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

Example of the `settings` object for TikTok. It requires an explicit `privacyLevel` choice; other fields control comments, duets, stitches, and content disclosure. `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
}

```

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

### curl example for captions API

Source: https://shapelessai.com/capabilities/subtitle-files

Example curl command to call the ShapelessAI captions API endpoint. It sends a POST request with an Authorization header and a JSON body containing the media_key, format, and names parameters.

```bash
curl -s https://shapelessai.com/api/captions -H "Authorization: Bearer $SHAPELESS_API_KEY" -H "Content-Type: application/json" -d '{"media_key":"<mediaKey>","format":"srt","names":["Shapeless"]}'
```

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

### Publish a post with CLI

Source: https://shapelessai.com/capabilities/publish-post

Use this CLI command to publish a post. It requires the connection ID and text, and the --queue flag schedules it for the next free slot.

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

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

### curl example for text-to-speech API

Source: https://shapelessai.com/capabilities/text-to-speech

Sends a POST request to the Shapeless speech API with an Authorization bearer token and a JSON body specifying text, voice, and energy. The example uses voice 'Kore' and energy 'energetic'.

```bash
curl -s https://shapelessai.com/api/speech -H "Authorization: Bearer $SHAPELESS_API_KEY" -H "Content-Type: application/json" -d '{"text":"We ship on Friday. Here is what changed.","voice":"Kore","energy":"energetic"}'
```

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

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

```

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

### Run brain onboarding with shapeless CLI

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

Use the shapeless CLI to run the brain onboarding process interactively.

```bash
shapeless brain onboarding
```

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

### POST /api/ai-tools/{slug}/verify

Source: https://shapelessai.com/capabilities/ai-tools-directory

Reads the maker's homepage now and returns badge state, followed, rel, a hint when missing, which agent surfaces the domain proves, our link's rel, and what to do next. Requires claim token as bearer for a listing in review; anyone for a live one, once a minute. No API key required.

```APIDOC
## POST /api/ai-tools/{slug}/verify

### Description
Reads the maker's homepage now and returns badge state, followed, rel, a hint when missing, which agent surfaces the domain proves, our link's rel, and what to do next. Requires claim token as bearer for a listing in review; anyone for a live one, once a minute. No API key required.

### Method
POST

### Endpoint
/api/ai-tools/{slug}/verify

### Path Parameters
- **slug** (string) - Required - The slug of the listing.

### Authentication
Optional: Bearer claim token for listings in review. No token for live listings (rate-limited to once per minute).

### Response
#### Success Response (200)
- **badgeFound** (boolean) - Whether the badge was found.
- **followed** (boolean) - Whether the badge is followed.
- **rel** (string) - The rel attribute of the badge link.
- **hint** (string) - Hint when badge is missing.
- **provenSurfaces** (array) - Agent surfaces the domain proves.
- **ourLinkRel** (string) - The rel attribute of our link.
- **nextSteps** (array) - What to do next.

#### Response Example
```json
{
  "badgeFound": true,
  "followed": true,
  "rel": "me",
  "hint": "",
  "provenSurfaces": ["surface1"],
  "ourLinkRel": "me",
  "nextSteps": ["step1"]
}
```
```

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

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

```

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

### demo_page (MCP)

Source: https://shapelessai.com/capabilities/record-demo

MCP tool that opens a URL in a real browser, performs the specified steps, and returns an MP4 media key with cursor and camera effects. Requires the write scope and a budget hold.

```APIDOC
## demo_page (MCP)

### Description
A real browser opens a URL and performs the steps you name (type, click, hover, scroll, wait); returns an MP4 media key drawn like a screen-recorded demo, with a cursor and camera that follow each action. A page behind a login demos as its login wall. Free: budgetUsd (default 2, max 10) is held while it runs and released. Needs the write scope.

### Method
MCP Tool

### Endpoint
Server: `https://shapelessai.com/mcp`

### Parameters
#### Request Body
- `url` (string) - Required - The absolute URL of the page to demo.
- `steps` (string) - Required - One step per line or semicolon: "type acme.com into the URL field; click Analyze; wait 2; hover the first result; scroll to Pricing". Add "for 2s" to hold a step longer.
- `name` (string) - Required - A 2-6 word filename for the clip, e.g. "analyze flow demo".
- `viewport` (string: `mobile`, `desktop`) - Optional - Which screen to demo on. mobile by default for a 9:16 clip (the page fills the reel), desktop otherwise or when the reel shows the desktop product.
- `aspect` (string: `9:16`, `1:1`, `16:9`) - Optional - The clip's shape. 9:16 by default so it fills a reel behind a cutout speaker.
- `zoom` (boolean) - Optional - Ease the camera onto each element touched. On by default; off shows the whole page.
- `browser_bar` (boolean) - Optional - Draw a browser bar with the address above the page. On by default.
- `budgetUsd` (number) - Optional - The most this call may spend, in USD (default 2, max 10). Held while the tool runs, released after.

### Response
Returns an MP4 media key.
```

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

### GET /api/ad-accounts

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

Retrieves ad accounts.

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

### Description
Retrieves ad accounts.

### Method
GET

### Endpoint
/api/ad-accounts

```

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

### Create and manage jobs with shapeless jobs commands

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

Commands to create, list, show, tail, continue, and stop jobs. The --label, --budget, and --watch flags customize job creation, --before <cursor> paginates older jobs, and --attach or --media-key add files to jobs.

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

```