Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: ShapelessAI Conversations API
version: '1'
description: 'The social media team an agent can call. Publish to LinkedIn, X, Instagram, TikTok, YouTube, Facebook, Threads, Bluesky, Reddit, Mastodon, Telegram, Discord and Pinterest, with each network''s limits checked first; make images, AI video, edits of your own footage, carousels, thumbnails, recorded product demos, speech and subtitles, one call each; or hand the whole goal to the agent team as a job. Every refusal says what to do next (a connect link, a checkout link, the question to ask). Bearer API key (Settings -> API keys) or the hosted MCP''s OAuth token. Read the docs live, not from memory: https://shapelessai.com/llms-full.txt is every docs and capability page in one fetch, prose at https://shapelessai.com/docs. What exists and what is planned: https://shapelessai.com/api/capabilities (an x-status: planned operation answers 501 with a want door).'
servers:
- url: https://shapelessai.com
tags:
- name: Conversations
paths:
/api/conversations:
get:
summary: Thread list, one page
operationId: getConversations
responses:
'200':
description: OK
'401':
description: No credential, or not valid.
'403':
description: The key is missing the "read" scope.
'429':
description: Over the key's rate limit (600 requests an hour).
security:
- apiKey:
- read
- oauth:
- read
x-scope: read
x-status: live
tags:
- Conversations
/api/conversations/{id}:
get:
summary: One transcript with each post artifact's queue state
operationId: getConversationsId
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
'401':
description: No credential, or not valid.
'403':
description: The key is missing the "read" scope.
'429':
description: Over the key's rate limit (600 requests an hour).
security:
- apiKey:
- read
- oauth:
- read
x-scope: read
x-status: live
tags:
- Conversations
patch:
summary: Rename a thread
operationId: patchConversationsId
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
'401':
description: No credential, or not valid.
'403':
description: The key is missing the "write" scope.
'429':
description: Over the key's rate limit (600 requests an hour).
security:
- apiKey:
- write
- oauth:
- write
x-scope: write
x-status: live
tags:
- Conversations
delete:
summary: Delete a thread
operationId: deleteConversationsId
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
'401':
description: No credential, or not valid.
'403':
description: The key is missing the "write" scope.
'429':
description: Over the key's rate limit (600 requests an hour).
security:
- apiKey:
- write
- oauth:
- write
x-scope: write
x-status: live
tags:
- Conversations
/api/conversations/{id}/opened:
post:
summary: Mark a thread opened
operationId: postConversationsIdOpened
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
'401':
description: No credential, or not valid.
'403':
description: The key is missing the "write" scope.
'429':
description: Over the key's rate limit (600 requests an hour).
security:
- apiKey:
- write
- oauth:
- write
x-scope: write
x-status: live
tags:
- Conversations
/api/conversations/{id}/panel:
get:
summary: 'The war room''s panel for this thread: the read-only document beside the chat on…'
operationId: getConversationsIdPanel
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: after
in: query
required: false
description: Answer once the panel's rev is past this (the rev you last read).
schema:
type: integer
minimum: 0
- name: wait
in: query
required: false
description: 'With after: hold up to this many seconds for a change, 25 at most.'
schema:
type: number
minimum: 0
maximum: 25
responses:
'200':
description: OK
'401':
description: No credential, or not valid.
'403':
description: The key is missing the "read" scope.
'429':
description: Over the key's rate limit (600 requests an hour).
security:
- apiKey:
- read
- oauth:
- read
x-scope: read
x-status: live
tags:
- Conversations
post:
summary: 'Change the panel: {ops: [...]} folded in order through the one reducer the…'
operationId: postConversationsIdPanel
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
ops:
type: array
minItems: 1
maxItems: 50
description: 'open {item, focus?}: show a tab (same item id replaces it in place). update {id, patch, focus?}: change fields of a tab, never its kind. show {id}: bring a tab to the front. close {id}. pick {id, optionId}: the person''s answer to a choices tab; on a story, pick {id, chapter, ref} ticks or unticks a reference and pick {id, chapter, optionId} picks one option of that chapter. chapter {id, chapter, focus?}: add one chapter to a story, or replace the one with the same id in place. mark {id, chapter, target, text}: the person''s one-line note on something in a story (target names it in words). edit {id, node, patch {title?, text?, sub?, media?}}: the person''s hand edit of one flow node (marked changed, the old value kept as was); edit {id, section, patch {text, cue?}}: their hand edit of one teleprompter section. suggest {suggestions: [{label, prompt, sub?, icon?}]}: the chips under the chat.'
items:
type: object
properties:
op:
type: string
enum:
- open
- update
- show
- close
- pick
- edit
- suggest
- chapter
- mark
item:
type: object
description: '{kind, title, id?, ...the kind''s fields}. node {node}; people; plan {messageId, blockIds}; calendar {ids?, highlight?, from?, to?, mode?: week|month|list}; performance {post?, days?}; agent {strategyId?}; choices {question, options: [{id, label, sub?, media?}]}; prompter {sections: [{text, kind?, seconds?, cue?, wpm?, tone?}], wordsPerMinute?} (text carries delivery marks: *words* harder, / a breath, // a full stop, ^word lifts); search {query, hits: [{id, title, ...}], groupBy?, orderBy?}; brain; media {items: [{kind: image|video|audio, src, title?}]}; custom {html, height?}; flow {nodes: [{id, kind, title, sub?, status?: planned|new|changed|running|done|failed|waiting, costUsd?, text?, refs?: [{title, url?, node?, why?}], media?, options?: [string], was?}], edges: [{from, to, label?}], estimateUsd?, approve?}; story {chapters: [{id, kind, title, note?, ...}]} where a chapter is references {refs: [{node | url (exactly one; url is http(s), off the graph), title, kind?: post|page|product|code|research (required with url), fit?: high|mid|low, why?, picked?, proof?: [{value, label, source?, asOf?}] (at most 4), excerpt? (at most 600 characters), thumb?}], leftOut?} | frames {seconds: [n], rows: [{id, label, sub?, node?, frames: [{src?, badge?, note?}], vs?, take?, you?}]} | options {options: [{id, label, sub?, text?, media?, refs?, chips?, count?}] (2 to 4), picked?, approve?} | compare {sides: [{label, node?, url?, ours?, median?}] (2 to 12), rows: [{label, values: [number|null, one per side], unit?, better?: higher|lower}]} (the older {a, b} row still reads as values [a, b] with two sides) | shots {shots: [{src, caption?, step?, flag?}], facts?: [{value, label}]}. A story src is a media key, a /path or an http(s) URL; any other scheme is refused.'
id:
type: string
patch:
type: object
focus:
type: boolean
optionId:
type: string
node:
type: string
description: 'edit: the flow node''s id.'
section:
type: integer
minimum: 0
description: 'edit: the teleprompter section''s index.'
chapter:
oneOf:
- type: object
- type: string
description: 'chapter: the story chapter, {id, kind, title, ...}. pick and mark on a story: the chapter''s id.'
ref:
type: string
description: 'pick on a story: the reference''s graph node, or its url when it is off the graph.'
target:
type: string
description: 'mark: what was marked, in words ("OpusClip x Airrack · 8 s").'
text:
type: string
description: 'mark: the person''s line.'
suggestions:
type: array
items:
type: object
required:
- op
required:
- ops
additionalProperties: false
responses:
'200':
description: OK
'401':
description: No credential, or not valid.
'403':
description: The key is missing the "write" scope.
'429':
description: Over the key's rate limit (600 requests an hour).
security:
- apiKey:
- write
- oauth:
- write
x-scope: write
x-status: live
tags:
- Conversations
/api/conversations/current/panel:
get:
summary: The panel of the thread the account opened last (the chat most likely open in…
operationId: getConversationsCurrentPanel
parameters:
- name: after
in: query
required: false
description: Answer once the panel's rev is past this (the rev you last read).
schema:
type: integer
minimum: 0
- name: wait
in: query
required: false
description: 'With after: hold up to this many seconds for a change, 25 at most.'
schema:
type: number
minimum: 0
maximum: 25
responses:
'200':
description: OK
'401':
description: No credential, or not valid.
'403':
description: The key is missing the "read" scope.
'429':
description: Over the key's rate limit (600 requests an hour).
security:
- apiKey:
- read
- oauth:
- read
x-scope: read
x-status: live
tags:
- Conversations
components:
securitySchemes:
apiKey:
type: http
scheme: bearer
description: slk_... key; scopes read, write, publish.
oauth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://shapelessai.com/api/auth/mcp/authorize
tokenUrl: https://shapelessai.com/api/auth/mcp/token
scopes:
read: Read anything the account holds.
write: 'Create and edit: jobs, drafts, agents, Brand Memory.'
publish: Anything that goes out to a platform, or spends.
wiki: Write to the wiki at /vizipedia as this account, and nothing else. A key with `write` covers it.