Content API

REST endpoints for the Content area of Lessly.

Copy page

The Content area publishes 31 REST endpoints. Paths are relative to https://api.lessly.com; see Authentication for the required header.

GET/content/channels

List the channels this product can publish to, with each one's limits and per-post cost. Seeded channels all use reminder delivery: the system prepares the post and notifies a person to publish it.

MCP tool: content_channels_list

Parameters

Name	In	Type	Required	Description
network	query	stringone of: linkedin, x, youtube, instagram, reddit	—	Return only channels on this network.
limit	query	integer	—	Maximum number of channels to return (1-100, default 50).
offset	query	integer	—	How many channels to skip, for paging.

Response

Returns object.

Field	Type	Always	Description
total	integer	•	Total number of matching channels, ignoring paging.
channels	object[]	•	The page of channels, ordered by network.

GET/content/channels/:id

Read one channel: its delivery mode and its capability descriptor — the character limit, media rules and cost to check before composing a variant for it.

MCP tool: content_channels_get

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The channel id returned by content_channels_list.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Channel id — pass this to content_publications_schedule.
network	string	•	Social network: linkedin, x, youtube, instagram or reddit.
pausedAt	string | null	•	ISO-8601 time the connector stopped working, or null when healthy. A paused channel keeps its scheduled publications — they are frozen, not cancelled, and dispatch once it resumes.
createdAt	string	•	ISO-8601 creation time.
updatedAt	string	•	ISO-8601 time of the last change.
connectorId	string | null	•	Platform connector this channel publishes through, or null for a reminder channel that needs none. An id — this toolkit never holds social credentials; a token is fetched per call and discarded.
displayName	string	•	Human label for the channel.
pauseReason	string | null	•	Why it paused: revoked (access was taken away), expired (the credential ran out), or the provider reason code from a failed publish. Null when healthy.
subjectType	stringone of: member, organization	•	Who publishes: member (a personal account) or organization (a company page). Phase 1 channels are all member accounts.
capabilities	object	•	What the channel accepts and what it costs: maxTextLength, maxMedia, supportsVideo, supportsLink, costPerPostUsd, costPerLinkPostUsd, dailyPostCeiling, ceilingIsRuntimeData. Read maxTextLength before writing a per-channel text variant.
deliveryMode	stringone of: auto, reminder	•	How the post reaches the network: auto (this API publishes it) or reminder (the system prepares it and notifies a person, who publishes by hand). Every seeded channel is reminder.

PATCH/content/channels/:id

Rename a channel, change its delivery mode, or correct its capability descriptor. Channels themselves are seeded, not created: every product starts with one per network.

MCP tool: content_channels_update

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The channel id returned by content_channels_list.
displayName	body	string	—	New human label for the channel. Omit to keep the current one.
deliveryMode	body	stringone of: auto, reminder	—	Change how the post reaches the network. Only reminder can be scheduled in this release — no publishing adapter exists yet.
capabilities	body	object	—	Override individual capability fields — a known ceiling beats the hand-filled constant. Merges over the existing descriptor; fields you omit keep their current values.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Channel id — pass this to content_publications_schedule.
network	string	•	Social network: linkedin, x, youtube, instagram or reddit.
pausedAt	string | null	•	ISO-8601 time the connector stopped working, or null when healthy. A paused channel keeps its scheduled publications — they are frozen, not cancelled, and dispatch once it resumes.
createdAt	string	•	ISO-8601 creation time.
updatedAt	string	•	ISO-8601 time of the last change.
connectorId	string | null	•	Platform connector this channel publishes through, or null for a reminder channel that needs none. An id — this toolkit never holds social credentials; a token is fetched per call and discarded.
displayName	string	•	Human label for the channel.
pauseReason	string | null	•	Why it paused: revoked (access was taken away), expired (the credential ran out), or the provider reason code from a failed publish. Null when healthy.
subjectType	stringone of: member, organization	•	Who publishes: member (a personal account) or organization (a company page). Phase 1 channels are all member accounts.
capabilities	object	•	What the channel accepts and what it costs: maxTextLength, maxMedia, supportsVideo, supportsLink, costPerPostUsd, costPerLinkPostUsd, dailyPostCeiling, ceilingIsRuntimeData. Read maxTextLength before writing a per-channel text variant.
deliveryMode	stringone of: auto, reminder	•	How the post reaches the network: auto (this API publishes it) or reminder (the system prepares it and notifies a person, who publishes by hand). Every seeded channel is reminder.

POST/content/channels/:id/bind

Bind a channel to a platform connector so posts can be published through it. Clears an existing pause — rebinding is how a revoked or expired connection is fixed. Pass deliveryMode "auto" to also switch the channel to automatic publishing; binding alone never does.

MCP tool: content_channels_bind

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The channel id returned by content_channels_list.
connectorId	body	string (uuid)	•	The platform connector to publish through — the id of a connector attached to this product, from the workspace connectors list. Networks with no publishing connector (instagram, LinkedIn company pages) are rejected.
deliveryMode	body	stringone of: auto, reminder	—	Pass auto to make this API publish through the connector. Omit to keep the current mode: binding alone never switches a channel to automatic publishing.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Channel id — pass this to content_publications_schedule.
network	string	•	Social network: linkedin, x, youtube, instagram or reddit.
pausedAt	string | null	•	ISO-8601 time the connector stopped working, or null when healthy. A paused channel keeps its scheduled publications — they are frozen, not cancelled, and dispatch once it resumes.
createdAt	string	•	ISO-8601 creation time.
updatedAt	string	•	ISO-8601 time of the last change.
connectorId	string | null	•	Platform connector this channel publishes through, or null for a reminder channel that needs none. An id — this toolkit never holds social credentials; a token is fetched per call and discarded.
displayName	string	•	Human label for the channel.
pauseReason	string | null	•	Why it paused: revoked (access was taken away), expired (the credential ran out), or the provider reason code from a failed publish. Null when healthy.
subjectType	stringone of: member, organization	•	Who publishes: member (a personal account) or organization (a company page). Phase 1 channels are all member accounts.
capabilities	object	•	What the channel accepts and what it costs: maxTextLength, maxMedia, supportsVideo, supportsLink, costPerPostUsd, costPerLinkPostUsd, dailyPostCeiling, ceilingIsRuntimeData. Read maxTextLength before writing a per-channel text variant.
deliveryMode	stringone of: auto, reminder	•	How the post reaches the network: auto (this API publishes it) or reminder (the system prepares it and notifies a person, who publishes by hand). Every seeded channel is reminder.

POST/content/channels/:id/resume

Resume a channel paused by a revoked or expired connection, once the connection works again. Its frozen publications dispatch on the next scheduler tick — late, not cancelled.

MCP tool: content_channels_resume

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The paused channel to resume, once its connector has been reconnected.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Channel id — pass this to content_publications_schedule.
network	string	•	Social network: linkedin, x, youtube, instagram or reddit.
pausedAt	string | null	•	ISO-8601 time the connector stopped working, or null when healthy. A paused channel keeps its scheduled publications — they are frozen, not cancelled, and dispatch once it resumes.
createdAt	string	•	ISO-8601 creation time.
updatedAt	string	•	ISO-8601 time of the last change.
connectorId	string | null	•	Platform connector this channel publishes through, or null for a reminder channel that needs none. An id — this toolkit never holds social credentials; a token is fetched per call and discarded.
displayName	string	•	Human label for the channel.
pauseReason	string | null	•	Why it paused: revoked (access was taken away), expired (the credential ran out), or the provider reason code from a failed publish. Null when healthy.
subjectType	stringone of: member, organization	•	Who publishes: member (a personal account) or organization (a company page). Phase 1 channels are all member accounts.
capabilities	object	•	What the channel accepts and what it costs: maxTextLength, maxMedia, supportsVideo, supportsLink, costPerPostUsd, costPerLinkPostUsd, dailyPostCeiling, ceilingIsRuntimeData. Read maxTextLength before writing a per-channel text variant.
deliveryMode	stringone of: auto, reminder	•	How the post reaches the network: auto (this API publishes it) or reminder (the system prepares it and notifies a person, who publishes by hand). Every seeded channel is reminder.

POST/content/channels/:id/unbind

Detach a channel from its platform connector, and clear any pause. Delivery mode is left as it is: an auto channel left without a connection fails its publications visibly rather than being silently downgraded to reminders.

MCP tool: content_channels_unbind

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The channel id returned by content_channels_list.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Channel id — pass this to content_publications_schedule.
network	string	•	Social network: linkedin, x, youtube, instagram or reddit.
pausedAt	string | null	•	ISO-8601 time the connector stopped working, or null when healthy. A paused channel keeps its scheduled publications — they are frozen, not cancelled, and dispatch once it resumes.
createdAt	string	•	ISO-8601 creation time.
updatedAt	string	•	ISO-8601 time of the last change.
connectorId	string | null	•	Platform connector this channel publishes through, or null for a reminder channel that needs none. An id — this toolkit never holds social credentials; a token is fetched per call and discarded.
displayName	string	•	Human label for the channel.
pauseReason	string | null	•	Why it paused: revoked (access was taken away), expired (the credential ran out), or the provider reason code from a failed publish. Null when healthy.
subjectType	stringone of: member, organization	•	Who publishes: member (a personal account) or organization (a company page). Phase 1 channels are all member accounts.
capabilities	object	•	What the channel accepts and what it costs: maxTextLength, maxMedia, supportsVideo, supportsLink, costPerPostUsd, costPerLinkPostUsd, dailyPostCeiling, ceilingIsRuntimeData. Read maxTextLength before writing a per-channel text variant.
deliveryMode	stringone of: auto, reminder	•	How the post reaches the network: auto (this API publishes it) or reminder (the system prepares it and notifies a person, who publishes by hand). Every seeded channel is reminder.

GET/content/media

List media assets, newest first, optionally filtered by storage status.

MCP tool: content_media_list

Parameters

Name	In	Type	Required	Description
status	query	stringone of: pending, ready, failed	—	Return only assets in this storage status.
limit	query	integer	—	Maximum number of assets to return (1-100, default 50).
offset	query	integer	—	How many assets to skip, for paging.

Response

Returns object.

Field	Type	Always	Description
total	integer	•	Total number of matching assets, ignoring paging.
assets	object[]	•	The page of assets, newest first.

POST/content/media

Ingest media from a public http(s) URL: the toolkit fetches it and stores it in the product bucket. Images and video up to 512 MB. A fetch that fails returns the asset with status "failed" and a reason rather than an error.

MCP tool: content_media_upload

Parameters

Name	In	Type	Required	Description
sourceUrl	body	string (uri)	•	Public http(s) URL the toolkit fetches server-side. Images and video only, up to 512 MB.
filename	body	string	—	Name to store the file under. Defaults to the last path segment of the URL.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Media asset id. Use it to attach the asset to a post.
key	string	•	Object key in the product bucket. Private — hand it to no one, it is not a URL.
mime	string | null	•	Stored media type, or null while still pending.
error	string | null	•	Why the asset is failed — a readable reason, or null when nothing went wrong.
source	stringone of: url, upload	•	How the bytes arrived: url (fetched by the toolkit) or upload (PUT by the app).
status	stringone of: pending, ready, failed	•	Storage status: pending (the bytes are not in the bucket yet) -> ready (stored, attachable to a post) or failed (ingestion gave up; see error).
filename	string | null	•	Original filename, kept for display only.
createdAt	string	•	ISO-8601 creation time.
sizeBytes	integer | null	•	Stored size in bytes, or null while pending.
sourceUrl	string | null	•	The URL the bytes were fetched from, if any.
updatedAt	string	•	ISO-8601 time of the last change.

GET/content/media/:id

Read one media asset: its storage status, type and size.

MCP tool: content_media_get

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The media asset id returned when it was created.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Media asset id. Use it to attach the asset to a post.
key	string	•	Object key in the product bucket. Private — hand it to no one, it is not a URL.
mime	string | null	•	Stored media type, or null while still pending.
error	string | null	•	Why the asset is failed — a readable reason, or null when nothing went wrong.
source	stringone of: url, upload	•	How the bytes arrived: url (fetched by the toolkit) or upload (PUT by the app).
status	stringone of: pending, ready, failed	•	Storage status: pending (the bytes are not in the bucket yet) -> ready (stored, attachable to a post) or failed (ingestion gave up; see error).
filename	string | null	•	Original filename, kept for display only.
createdAt	string	•	ISO-8601 creation time.
sizeBytes	integer | null	•	Stored size in bytes, or null while pending.
sourceUrl	string | null	•	The URL the bytes were fetched from, if any.
updatedAt	string	•	ISO-8601 time of the last change.

POST/content/media/:id/finalize

Confirm a signed-URL upload. The bucket is asked what was actually stored, and the asset becomes ready. Fails while no object has been uploaded yet.

MCP tool: content_media_finalize

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The media asset id returned when it was created.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Media asset id. Use it to attach the asset to a post.
key	string	•	Object key in the product bucket. Private — hand it to no one, it is not a URL.
mime	string | null	•	Stored media type, or null while still pending.
error	string | null	•	Why the asset is failed — a readable reason, or null when nothing went wrong.
source	stringone of: url, upload	•	How the bytes arrived: url (fetched by the toolkit) or upload (PUT by the app).
status	stringone of: pending, ready, failed	•	Storage status: pending (the bytes are not in the bucket yet) -> ready (stored, attachable to a post) or failed (ingestion gave up; see error).
filename	string | null	•	Original filename, kept for display only.
createdAt	string	•	ISO-8601 creation time.
sizeBytes	integer | null	•	Stored size in bytes, or null while pending.
sourceUrl	string | null	•	The URL the bytes were fetched from, if any.
updatedAt	string	•	ISO-8601 time of the last change.

POST/content/media/upload-url

Get a time-limited signed URL to PUT a file straight into the product bucket. Creates a pending asset; call content_media_finalize once the upload finishes.

MCP tool: content_media_create_upload_url

Parameters

Name	In	Type	Required	Description
contentType	body	string	•	The media type the app will PUT, e.g. video/mp4. Must be image/* or video/*.
filename	body	string	—	Name to store the file under, for display purposes.

Response

Returns object.

Field	Type	Always	Description
asset	object	•	The pending asset row. It turns ready on finalize.
expiresAt	string	•	ISO-8601 time after which the upload URL stops working.
uploadUrl	string	•	Time-limited signed PUT URL. Upload the bytes to it, then call the finalize tool.
contentType	string	•	The Content-Type header the PUT must send — the signature covers it.

GET/content/metrics/channels/:id

Daily snapshots of a channel itself — follower count and channel-level reach over time. Sampled once a day while the channel is publishing; a channel with nothing published in the last 30 days stops being sampled, and one whose network reports no analytics is never sampled at all.

MCP tool: content_metrics_channel_series

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The channel id, from content_channels_list.
from	query	string (date-time)	—	ISO-8601 lower bound on capture time, inclusive. Omit for "from the beginning".
to	query	string (date-time)	—	ISO-8601 upper bound on capture time, inclusive. Omit for "up to now".
limit	query	integer	—	Maximum number of snapshots to return, oldest first.

Response

Returns object.

Field	Type	Always	Description
points	object[]	•	Daily snapshots, oldest first.
network	string	•	The network the channel publishes to.
analytics	stringone of: full, basic, none	•	What this network reports for this account. "none" means no snapshot will ever be taken — a personal Instagram profile has no API at all; "basic" means fewer numbers than a business account gets, so an absent metric is the network's silence, not a zero.
channelId	string	•	The channel these snapshots belong to.

GET/content/metrics/posts/:id

Metric snapshots of one published post on one channel, over time — how reach and engagement grew, not a single current number. Sampled hourly for the first day, then daily, then weekly, then never: a post stops growing and the polling stops with it. Empty until the first snapshot, and always empty where analytics is "none".

MCP tool: content_metrics_post_series

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The publication id, from content_publications_schedule or content_publications_list.
from	query	string (date-time)	—	ISO-8601 lower bound on capture time, inclusive. Omit for "from the beginning".
to	query	string (date-time)	—	ISO-8601 upper bound on capture time, inclusive. Omit for "up to now".
limit	query	integer	—	Maximum number of snapshots to return, oldest first.

Response

Returns object.

Field	Type	Always	Description
points	object[]	•	Snapshots oldest first. Readings over time, not a current value: reach keeps growing for weeks. Empty means nothing has been captured yet.
network	string	•	The network the channel publishes to.
analytics	stringone of: full, basic, none	•	What this network reports for this account. "none" means no snapshot will ever be taken — a personal Instagram profile has no API at all; "basic" means fewer numbers than a business account gets, so an absent metric is the network's silence, not a zero.
channelId	string	•	The channel it was published to.
publicationId	string	•	The publication these snapshots belong to.

GET/content/posts

List posts, newest first, optionally filtered by lifecycle status.

MCP tool: content_posts_list

Parameters

Name	In	Type	Required	Description
status	query	stringone of: draft, pending_approval, approved, scheduled, published, failed	—	Return only posts in this status.
limit	query	integer	—	Maximum number of posts to return (1-100, default 50).
offset	query	integer	—	How many posts to skip, for paging.

Response

Returns object.

Field	Type	Always	Description
posts	object[]	•	The page of posts, newest first.
total	integer	•	Total number of matching posts, ignoring paging.

POST/content/posts

Create a post. It starts as a draft at version 1; submit it for approval when the text is ready.

MCP tool: content_posts_create

Parameters

Name	In	Type	Required	Description
text	body	string	•	The post text, channel-independent, written in markdown — bold, italic, lists, links. Each network gets it flattened to the plain text that network accepts; content_publications_validate shows exactly what that looks like per channel. Per-channel variants come later, at publish time.
media	body	string[]	—	Media references attached to the post, in display order. Opaque strings — the toolkit does not upload or resolve them.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Post id.
text	string	•	The current text of the post, in markdown.
media	string[]	•	Media references attached to the current version.
author	string	•	Identity id of whoever composed the post.
status	stringone of: draft, pending_approval, approved, scheduled, published, failed	•	Post lifecycle status: draft (being written) -> pending_approval (submitted) -> approved (cleared to publish); scheduled/published/failed are set by the publishing pipeline.
createdAt	string	•	ISO-8601 creation time.
updatedAt	string	•	ISO-8601 time of the last change.
currentVersion	integer	•	Version number of the current text.
approvedVersion	integer | null	•	The version an approval binds to, or null. Cleared on every edit: approving one text never covers another.

GET/content/posts/:id

Read one post: its current text, status and version numbers.

MCP tool: content_posts_get

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The post id returned by content_posts_create.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Post id.
text	string	•	The current text of the post, in markdown.
media	string[]	•	Media references attached to the current version.
author	string	•	Identity id of whoever composed the post.
status	stringone of: draft, pending_approval, approved, scheduled, published, failed	•	Post lifecycle status: draft (being written) -> pending_approval (submitted) -> approved (cleared to publish); scheduled/published/failed are set by the publishing pipeline.
createdAt	string	•	ISO-8601 creation time.
updatedAt	string	•	ISO-8601 time of the last change.
currentVersion	integer	•	Version number of the current text.
approvedVersion	integer | null	•	The version an approval binds to, or null. Cleared on every edit: approving one text never covers another.

PATCH/content/posts/:id

Edit a post. The edit is recorded as a new immutable version; an edit to an approved post returns it to pending_approval, because an approval binds to one specific text.

MCP tool: content_posts_update

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The post id returned by content_posts_create.
text	body	string	—	Replacement text, in markdown. Omit to keep the current text.
media	body	string[]	—	Replacement media list (replaces, never merges). Omit to keep the current media.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Post id.
text	string	•	The current text of the post, in markdown.
media	string[]	•	Media references attached to the current version.
author	string	•	Identity id of whoever composed the post.
status	stringone of: draft, pending_approval, approved, scheduled, published, failed	•	Post lifecycle status: draft (being written) -> pending_approval (submitted) -> approved (cleared to publish); scheduled/published/failed are set by the publishing pipeline.
createdAt	string	•	ISO-8601 creation time.
updatedAt	string	•	ISO-8601 time of the last change.
currentVersion	integer	•	Version number of the current text.
approvedVersion	integer | null	•	The version an approval binds to, or null. Cleared on every edit: approving one text never covers another.

POST/content/posts/:id/approve

Approve a post awaiting approval. The approval binds to the current version — a later edit revokes it.

MCP tool: content_posts_approve

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The post id returned by content_posts_create.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Post id.
text	string	•	The current text of the post, in markdown.
media	string[]	•	Media references attached to the current version.
author	string	•	Identity id of whoever composed the post.
status	stringone of: draft, pending_approval, approved, scheduled, published, failed	•	Post lifecycle status: draft (being written) -> pending_approval (submitted) -> approved (cleared to publish); scheduled/published/failed are set by the publishing pipeline.
createdAt	string	•	ISO-8601 creation time.
updatedAt	string	•	ISO-8601 time of the last change.
currentVersion	integer	•	Version number of the current text.
approvedVersion	integer | null	•	The version an approval binds to, or null. Cleared on every edit: approving one text never covers another.

POST/content/posts/:id/media/attach

Attach stored media assets to a post, appended in the given order. Only assets that are ready can be attached. This counts as an edit: the post gets a new version and an approved post returns to pending_approval.

MCP tool: content_posts_attach_media

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The post id.
mediaIds	body	string (uuid)[]	•	Media asset ids, in the order they should appear on the post.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Post id.
text	string	•	The current text of the post, in markdown.
media	string[]	•	Media references attached to the current version.
author	string	•	Identity id of whoever composed the post.
status	stringone of: draft, pending_approval, approved, scheduled, published, failed	•	Post lifecycle status: draft (being written) -> pending_approval (submitted) -> approved (cleared to publish); scheduled/published/failed are set by the publishing pipeline.
createdAt	string	•	ISO-8601 creation time.
updatedAt	string	•	ISO-8601 time of the last change.
currentVersion	integer	•	Version number of the current text.
approvedVersion	integer | null	•	The version an approval binds to, or null. Cleared on every edit: approving one text never covers another.

POST/content/posts/:id/media/detach

Remove media assets from a post, keeping the order of the rest. Like any edit, it produces a new version and returns an approved post to pending_approval.

MCP tool: content_posts_detach_media

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The post id.
mediaIds	body	string (uuid)[]	•	Media asset ids to remove from the post.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Post id.
text	string	•	The current text of the post, in markdown.
media	string[]	•	Media references attached to the current version.
author	string	•	Identity id of whoever composed the post.
status	stringone of: draft, pending_approval, approved, scheduled, published, failed	•	Post lifecycle status: draft (being written) -> pending_approval (submitted) -> approved (cleared to publish); scheduled/published/failed are set by the publishing pipeline.
createdAt	string	•	ISO-8601 creation time.
updatedAt	string	•	ISO-8601 time of the last change.
currentVersion	integer	•	Version number of the current text.
approvedVersion	integer | null	•	The version an approval binds to, or null. Cleared on every edit: approving one text never covers another.

POST/content/posts/:id/submit

Submit a draft for approval. Only a draft can be submitted.

MCP tool: content_posts_submit

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The post id returned by content_posts_create.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Post id.
text	string	•	The current text of the post, in markdown.
media	string[]	•	Media references attached to the current version.
author	string	•	Identity id of whoever composed the post.
status	stringone of: draft, pending_approval, approved, scheduled, published, failed	•	Post lifecycle status: draft (being written) -> pending_approval (submitted) -> approved (cleared to publish); scheduled/published/failed are set by the publishing pipeline.
createdAt	string	•	ISO-8601 creation time.
updatedAt	string	•	ISO-8601 time of the last change.
currentVersion	integer	•	Version number of the current text.
approvedVersion	integer | null	•	The version an approval binds to, or null. Cleared on every edit: approving one text never covers another.

GET/content/posts/:id/versions

List every version of a post, oldest first — the audit trail of what was written and by whom.

MCP tool: content_posts_versions

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The post id returned by content_posts_create.

Response

Returns object.

Field	Type	Always	Description
postId	string	•	The post these versions belong to.
versions	object[]	•	Every version, oldest first.

GET/content/publications

List publications — the queue and the timeline — newest slot first.

MCP tool: content_publications_list

Parameters

Name	In	Type	Required	Description
state	query	stringone of: pending, publishing, published, failed, cancelled	—	Return only publications in this state.
postId	query	string (uuid)	—	Return only publications of this post.
channelId	query	string (uuid)	—	Return only publications to this channel.
limit	query	integer	—	Maximum number to return (1-100, default 50).
offset	query	integer	—	How many to skip, for paging.
scheduledFrom	query	string (date-time)	—	Return only publications scheduled at or after this ISO-8601 time.
scheduledTo	query	string (date-time)	—	Return only publications scheduled at or before this ISO-8601 time.

Response

Returns object.

Field	Type	Always	Description
total	integer	•	Total number of matching publications, ignoring paging.
publications	object[]	•	The page of publications, newest slot first.

POST/content/publications

Queue an approved post for publication to one channel at a given time. On a reminder channel this does not call the network: at the scheduled time a person is notified to publish by hand, and confirms afterwards with content_publications_confirm.

MCP tool: content_publications_schedule

Parameters

Name	In	Type	Required	Description
postId	body	string (uuid)	•	The post to publish. It must already be approved — an unapproved text never publishes.
channelId	body	string (uuid)	•	The channel to publish to. Get its character limit from content_channels_get first.
scheduledAt	body	string (date-time)	•	ISO-8601 time to publish. In the past means "as soon as the next tick runs".
text	body	string	—	Per-channel variant of the text, in markdown. Omit to use the post text. It is rendered to plain network text before it is stored — call content_publications_validate first if you want to see the result.
idempotencyKey	body	string	—	Your own key for this publishing intent, unique within the product. Resending the same key returns the SAME publication instead of creating a second one — a duplicate in a client feed is the worst defect this product can ship. Omit it and one is derived from post, channel and time.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Publication id.
text	string	•	The exact text that will be published to this channel — markdown already flattened to plain network text at schedule time. Not the markdown source; that stays on the post.
state	stringone of: pending, publishing, published, failed, cancelled	•	pending (queued) -> publishing (the reminder was sent; a person is publishing by hand) -> published (confirmed) | failed | cancelled.
postId	string	•	The post being published.
costUsd	number | null	•	What publishing this costs in USD, computed when it was scheduled. On X a post carrying a link costs 13x a plain one. Null means the cost is not known — an auto channel refuses to dispatch it.
attempts	integer	•	How many dispatch attempts have been made.
channelId	string	•	The channel it is published to.
costBasis	string | null	•	Which rate produced costUsd: "plain", "link" or "free".
createdAt	string	•	ISO-8601 creation time.
lastError	string | null	•	The most recent failure, if any.
updatedAt	string	•	ISO-8601 time of the last change.
externalId	string | null	•	The network's id for the published post, once known.
externalUrl	string | null	•	URL of the published post, once known.
publishedAt	string | null	•	ISO-8601 time it was confirmed published.
scheduledAt	string	•	ISO-8601 time the publication is due.
reminderCount	integer	•	How many reminders have been sent for this publication.
idempotencyKey	string	•	The key that makes a retry the same publication.
reminderSentAt	string | null	•	ISO-8601 time the most recent reminder went out, or null if none has.

GET/content/publications/:id

Read one publication: its state, its slot, and where it ended up.

MCP tool: content_publications_get

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The publication id returned by content_publications_schedule.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Publication id.
text	string	•	The exact text that will be published to this channel — markdown already flattened to plain network text at schedule time. Not the markdown source; that stays on the post.
state	stringone of: pending, publishing, published, failed, cancelled	•	pending (queued) -> publishing (the reminder was sent; a person is publishing by hand) -> published (confirmed) | failed | cancelled.
postId	string	•	The post being published.
costUsd	number | null	•	What publishing this costs in USD, computed when it was scheduled. On X a post carrying a link costs 13x a plain one. Null means the cost is not known — an auto channel refuses to dispatch it.
attempts	integer	•	How many dispatch attempts have been made.
channelId	string	•	The channel it is published to.
costBasis	string | null	•	Which rate produced costUsd: "plain", "link" or "free".
createdAt	string	•	ISO-8601 creation time.
lastError	string | null	•	The most recent failure, if any.
updatedAt	string	•	ISO-8601 time of the last change.
externalId	string | null	•	The network's id for the published post, once known.
externalUrl	string | null	•	URL of the published post, once known.
publishedAt	string | null	•	ISO-8601 time it was confirmed published.
scheduledAt	string	•	ISO-8601 time the publication is due.
reminderCount	integer	•	How many reminders have been sent for this publication.
idempotencyKey	string	•	The key that makes a retry the same publication.
reminderSentAt	string | null	•	ISO-8601 time the most recent reminder went out, or null if none has.

POST/content/publications/:id/cancel

Cancel a publication that has not finished. A publication whose reminder already went out can still be cancelled — until someone confirms it.

MCP tool: content_publications_cancel

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The publication id returned by content_publications_schedule.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Publication id.
text	string	•	The exact text that will be published to this channel — markdown already flattened to plain network text at schedule time. Not the markdown source; that stays on the post.
state	stringone of: pending, publishing, published, failed, cancelled	•	pending (queued) -> publishing (the reminder was sent; a person is publishing by hand) -> published (confirmed) | failed | cancelled.
postId	string	•	The post being published.
costUsd	number | null	•	What publishing this costs in USD, computed when it was scheduled. On X a post carrying a link costs 13x a plain one. Null means the cost is not known — an auto channel refuses to dispatch it.
attempts	integer	•	How many dispatch attempts have been made.
channelId	string	•	The channel it is published to.
costBasis	string | null	•	Which rate produced costUsd: "plain", "link" or "free".
createdAt	string	•	ISO-8601 creation time.
lastError	string | null	•	The most recent failure, if any.
updatedAt	string	•	ISO-8601 time of the last change.
externalId	string | null	•	The network's id for the published post, once known.
externalUrl	string | null	•	URL of the published post, once known.
publishedAt	string | null	•	ISO-8601 time it was confirmed published.
scheduledAt	string	•	ISO-8601 time the publication is due.
reminderCount	integer	•	How many reminders have been sent for this publication.
idempotencyKey	string	•	The key that makes a retry the same publication.
reminderSentAt	string | null	•	ISO-8601 time the most recent reminder went out, or null if none has.

POST/content/publications/:id/confirm

Confirm that a person published the post by hand, optionally with the URL it landed at. This closes the publication. It stays available after the fact — reminded, published, forgot to confirm, confirm later is a normal sequence.

MCP tool: content_publications_confirm

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The publication id returned by content_publications_schedule.
externalUrl	body	string (uri)	—	URL of the post the person actually published. Worth supplying — it is what identifies the post later.
externalId	body	string	—	The network's own id for the post, if known.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Publication id.
text	string	•	The exact text that will be published to this channel — markdown already flattened to plain network text at schedule time. Not the markdown source; that stays on the post.
state	stringone of: pending, publishing, published, failed, cancelled	•	pending (queued) -> publishing (the reminder was sent; a person is publishing by hand) -> published (confirmed) | failed | cancelled.
postId	string	•	The post being published.
costUsd	number | null	•	What publishing this costs in USD, computed when it was scheduled. On X a post carrying a link costs 13x a plain one. Null means the cost is not known — an auto channel refuses to dispatch it.
attempts	integer	•	How many dispatch attempts have been made.
channelId	string	•	The channel it is published to.
costBasis	string | null	•	Which rate produced costUsd: "plain", "link" or "free".
createdAt	string	•	ISO-8601 creation time.
lastError	string | null	•	The most recent failure, if any.
updatedAt	string	•	ISO-8601 time of the last change.
externalId	string | null	•	The network's id for the published post, once known.
externalUrl	string | null	•	URL of the published post, once known.
publishedAt	string | null	•	ISO-8601 time it was confirmed published.
scheduledAt	string	•	ISO-8601 time the publication is due.
reminderCount	integer	•	How many reminders have been sent for this publication.
idempotencyKey	string	•	The key that makes a retry the same publication.
reminderSentAt	string | null	•	ISO-8601 time the most recent reminder went out, or null if none has.

POST/content/publications/:id/remind

Send the publish reminder AGAIN. Repeat reminders are never automatic: the system cannot double-publish, but a person can, so a second nudge only ever happens because someone asked for it.

MCP tool: content_publications_remind

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The publication id returned by content_publications_schedule.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Publication id.
text	string	•	The exact text that will be published to this channel — markdown already flattened to plain network text at schedule time. Not the markdown source; that stays on the post.
state	stringone of: pending, publishing, published, failed, cancelled	•	pending (queued) -> publishing (the reminder was sent; a person is publishing by hand) -> published (confirmed) | failed | cancelled.
postId	string	•	The post being published.
costUsd	number | null	•	What publishing this costs in USD, computed when it was scheduled. On X a post carrying a link costs 13x a plain one. Null means the cost is not known — an auto channel refuses to dispatch it.
attempts	integer	•	How many dispatch attempts have been made.
channelId	string	•	The channel it is published to.
costBasis	string | null	•	Which rate produced costUsd: "plain", "link" or "free".
createdAt	string	•	ISO-8601 creation time.
lastError	string | null	•	The most recent failure, if any.
updatedAt	string	•	ISO-8601 time of the last change.
externalId	string | null	•	The network's id for the published post, once known.
externalUrl	string | null	•	URL of the published post, once known.
publishedAt	string | null	•	ISO-8601 time it was confirmed published.
scheduledAt	string	•	ISO-8601 time the publication is due.
reminderCount	integer	•	How many reminders have been sent for this publication.
idempotencyKey	string	•	The key that makes a retry the same publication.
reminderSentAt	string | null	•	ISO-8601 time the most recent reminder went out, or null if none has.

POST/content/publications/:id/reschedule

Move a publication to a new time. It returns to the queue, and the reminder for the old slot is spent — a new one goes out at the new time.

MCP tool: content_publications_reschedule

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	•	The publication id returned by content_publications_schedule.
scheduledAt	body	string (date-time)	•	New ISO-8601 time. The publication returns to the queue.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Publication id.
text	string	•	The exact text that will be published to this channel — markdown already flattened to plain network text at schedule time. Not the markdown source; that stays on the post.
state	stringone of: pending, publishing, published, failed, cancelled	•	pending (queued) -> publishing (the reminder was sent; a person is publishing by hand) -> published (confirmed) | failed | cancelled.
postId	string	•	The post being published.
costUsd	number | null	•	What publishing this costs in USD, computed when it was scheduled. On X a post carrying a link costs 13x a plain one. Null means the cost is not known — an auto channel refuses to dispatch it.
attempts	integer	•	How many dispatch attempts have been made.
channelId	string	•	The channel it is published to.
costBasis	string | null	•	Which rate produced costUsd: "plain", "link" or "free".
createdAt	string	•	ISO-8601 creation time.
lastError	string | null	•	The most recent failure, if any.
updatedAt	string	•	ISO-8601 time of the last change.
externalId	string | null	•	The network's id for the published post, once known.
externalUrl	string | null	•	URL of the published post, once known.
publishedAt	string | null	•	ISO-8601 time it was confirmed published.
scheduledAt	string	•	ISO-8601 time the publication is due.
reminderCount	integer	•	How many reminders have been sent for this publication.
idempotencyKey	string	•	The key that makes a retry the same publication.
reminderSentAt	string | null	•	ISO-8601 time the most recent reminder went out, or null if none has.

POST/content/publications/publish

Publish NOW: the same queue, scheduled for this instant. There is no separate synchronous path — a fast path would differ exactly where it matters, on failure.

MCP tool: content_publications_publish

Parameters

Name	In	Type	Required	Description
postId	body	string (uuid)	•	The post to publish. It must already be approved.
channelId	body	string (uuid)	•	The channel to publish to.
text	body	string	—	Per-channel variant of the text, in markdown. Omit to use the post text. It is rendered to plain network text before it is stored — call content_publications_validate first if you want to see the result.
idempotencyKey	body	string	—	Your own key for this publishing intent, unique within the product. Resending the same key returns the SAME publication instead of creating a second one — a duplicate in a client feed is the worst defect this product can ship. Omit it and one is derived from post, channel and time.

Response

Returns object.

Field	Type	Always	Description
id	string	•	Publication id.
text	string	•	The exact text that will be published to this channel — markdown already flattened to plain network text at schedule time. Not the markdown source; that stays on the post.
state	stringone of: pending, publishing, published, failed, cancelled	•	pending (queued) -> publishing (the reminder was sent; a person is publishing by hand) -> published (confirmed) | failed | cancelled.
postId	string	•	The post being published.
costUsd	number | null	•	What publishing this costs in USD, computed when it was scheduled. On X a post carrying a link costs 13x a plain one. Null means the cost is not known — an auto channel refuses to dispatch it.
attempts	integer	•	How many dispatch attempts have been made.
channelId	string	•	The channel it is published to.
costBasis	string | null	•	Which rate produced costUsd: "plain", "link" or "free".
createdAt	string	•	ISO-8601 creation time.
lastError	string | null	•	The most recent failure, if any.
updatedAt	string	•	ISO-8601 time of the last change.
externalId	string | null	•	The network's id for the published post, once known.
externalUrl	string | null	•	URL of the published post, once known.
publishedAt	string | null	•	ISO-8601 time it was confirmed published.
scheduledAt	string	•	ISO-8601 time the publication is due.
reminderCount	integer	•	How many reminders have been sent for this publication.
idempotencyKey	string	•	The key that makes a retry the same publication.
reminderSentAt	string | null	•	ISO-8601 time the most recent reminder went out, or null if none has.

POST/content/publications/validate

Dry run: check a post against one or more channels WITHOUT scheduling anything. Returns everything that would go wrong — text too long, media not stored yet, attachments a network will not take, a link it will not linkify — and what publishing would cost. On X a post carrying a link costs $0.20 against $0.015 for a plain one, so call this before you schedule.

MCP tool: content_publications_validate

Parameters

Name	In	Type	Required	Description
postId	body	string (uuid)	•	The post to check. It does not have to be approved yet — this never publishes.
channels	body	object[]	•	One entry per channel you are considering. Check them all in one call.
scheduledAt	body	string (date-time)	—	The slot you intend to use, ISO-8601. Only the daily ceiling depends on it; omit for "now".

Response

Returns object.

Field	Type	Always	Description
postId	string	•	The post that was checked.
channels	object[]	•	One result per requested channel, in the order they were given.