1Post API reference: every route, key and role

API reference

The 1Post API has 128 operations for posts, media, accounts, slots, the library, webhooks, results, the inbox and automation. Authenticate with a key bound to a workspace. Each entry lists its method, path, what it does, the key scope and role action it needs, its parameters and the fields of its request body.

This reference is generated from the API's own route table. Public routes are listed here; vendor callbacks and service routes are left out. There are 128 operations in 23 groups. Every request needs a key unless the table says No key; see authentication. The machine-readable document is at /openapi.json on the API host.

Posts

POST/v1/bulk/posts/approve

Approve up to 100 posts waiting in review and schedule them

Needs a role that approves (owner, admin, reviewer). A key or MCP client also needs the approval switch only the workspace owner sets. Each post is checked and scheduled on its own, so one that no longer fits is reported beside its id.

Needs a write key. Role action: post.approve.

Body field	Type	Required
`post_ids`	string[]	Yes

Errors: invalid_input unauthorized forbidden rate_limited internal_error

POST/v1/bulk/posts/delete

Delete up to 100 unscheduled posts or scheduled posts

A post that is live on a platform is not removed there and is refused for that id only.

Needs a write key. Role action: post.create.

Body field	Type	Required
`post_ids`	string[]	Yes

Errors: invalid_input unauthorized forbidden rate_limited internal_error

POST/v1/bulk/posts/reschedule

Move up to 100 posts to a new time

Posts are moved in the order given, spacing_min minutes apart, starting at schedule_at. Each post is its own step: one that is refused (a full day, a post already sent) is reported beside its id and the others still move. The answer lists every id.

Needs a write key. Role action: post.create.

Body field	Type	Required
`post_ids`	string[]	Yes
`schedule_at`	string	Yes
`spacing_min`	integer	No

Errors: results invalid_input horizon unauthorized queue_limit allowance_used forbidden daily_cap rate_limited internal_error

GET/v1/posts

List posts, newest first, with their destinations

Needs a read key. Role action: read.

Parameter	In	Type	Required
`limit`	query	string	No
`cursor`	query	string	No
`status`	query	string (one of a fixed list)	No
`platform`	query	string (one of a fixed list)	No
`account_id`	query	string	No
`tag`	query	string	No
`from`	query	string	No
`to`	query	string	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

POST/v1/posts

Save an unscheduled post, schedule a post or publish now to one or more accounts

Without schedule_at, publish_now or use_next_free_slot the post is saved as an unscheduled post. schedule_at is an ISO 8601 time (no offset means UTC) and wins over use_next_free_slot. A contributor's post goes to review whatever the request asks for, and a test key's post is always a dry run. Idempotency-Key is honored for 24 hours: the same key with the same request returns the first answer, with a different request it is a 409.

Needs a write key. Role action: post.create.

Parameter	In	Type	Required
`Idempotency-Key`	header	string	No

Body field	Type	Required
`text`	string	No
`parts`	object[]	No
`accounts`	string or object[]	No
`set_id`	string	No
`signature_id`	string or null	No
`tags`	string[]	No
`publish_now`	boolean	No
`schedule_at`	string	No
`use_next_free_slot`	boolean	No
`late_policy`	"skip" \| "publish"	No
`late_window_min`	integer	No
`dry_run`	boolean	No
`review_link`	boolean	No

Errors: published invalid_input horizon unauthorized queue_limit allowance_used subscription_required forbidden reconnect_needed daily_cap no_free_slot invalid_for_platform rate_limited internal_error

GET/v1/posts/{id}

Read one post with the state of each destination

Needs a read key. Role action: read.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: unauthorized forbidden not_found rate_limited internal_error

PATCH/v1/posts/{id}

Change part of a post before it goes out, or move it in time

Send only what changes. parts replaces the post's text and media (destinations with their own text keep it); accounts patches destinations already on the post by account_id, or adds new ones; remove_accounts drops destinations. A scheduled post is taken back to an unscheduled post, changed, validated again and scheduled at the same time, all or nothing. A post that already went out can only move, with move.choice.

Needs a write key. Role action: post.create.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`parts`	object[]	No
`accounts`	object[]	No
`remove_accounts`	string[]	No
`tags`	string[]	No
`late_policy`	"skip" \| "publish"	No
`late_window_min`	integer	No
`schedule_at`	string	No
`publish_now`	boolean	No
`move`	object	No

Errors: kept invalid_input horizon unauthorized allowance_used queue_limit forbidden not_found daily_cap reconnect_needed invalid_for_platform rate_limited internal_error

DELETE/v1/posts/{id}

Delete an unscheduled post or cancel a schedule, for every destination or one

A destination that is live on a platform is not removed there. With account_id only that destination goes.

Needs a write key. Role action: post.create.

Parameter	In	Type	Required
`id`	path	string	Yes
`account_id`	query	string	No

Errors: deleted invalid_input unauthorized forbidden not_found rate_limited internal_error

POST/v1/posts/{id}/approve

Approve a post waiting in review and schedule it

Also schedules a post a client already approved through a review link. Needs a role that approves (owner, admin, reviewer). A key or MCP client also needs the approval switch only the workspace owner sets.

Needs a write key. Role action: post.approve.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: invalid_input unauthorized forbidden not_found rate_limited internal_error

POST/v1/posts/{id}/cancel

Cancel every destination of a post that has not started

A destination whose publish is in flight is left to finish, and is counted in in_flight.

Needs a write key. Role action: post.create.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`account_id`	string	No

Errors: invalid_input unauthorized forbidden not_found rate_limited internal_error

GET/v1/posts/{id}/comments

Read the team comments and client comments on a post

Needs a read key. Role action: read.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: unauthorized forbidden not_found rate_limited internal_error

POST/v1/posts/{id}/comments

Leave a team comment on a post

Needs a write key. Role action: post.comment.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`text`	string	Yes

Errors: invalid_input unauthorized forbidden not_found rate_limited internal_error

POST/v1/posts/{id}/duplicate

Copy a post into a new unscheduled post

Needs a write key. Role action: post.create.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: unauthorized forbidden not_found rate_limited internal_error

POST/v1/posts/{id}/link-live

Attach the live platform post to a destination whose outcome was unknown

Send the platform's own id or the post's address. The destination becomes published and its results are collected from then on.

Needs a write key. Role action: post.publish.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`account_id`	string	Yes
`platform_post_id`	string	No
`url`	string	No

Errors: invalid_input unauthorized forbidden not_found rate_limited internal_error

POST/v1/posts/{id}/request-changes

Send a post in review back to its author with a note

Needs a write key. Role action: post.approve.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`text`	string	Yes

Errors: invalid_input unauthorized forbidden not_found rate_limited internal_error

POST/v1/posts/{id}/retry

Send the destinations that failed again, as a new post

Only a destination known not to have published (failed) is retried. A destination in unknown may already be on the platform: check the account, then attach it with link-live or duplicate the post.

Needs a write key. Role action: post.publish.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: unauthorized forbidden not_found outcome_unknown rate_limited internal_error

POST/v1/posts/{id}/review-links

Make a link a client opens to preview, comment on and approve a post

The link works without a 1Post login, expires after 7 days unless ttl_days says up to 30, and can be revoked. The token is in this response only.

Needs a write key. Role action: reviewlink.create.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`post_ids`	string[]	No
`ttl_days`	integer	No

Errors: invalid_input unauthorized forbidden not_found rate_limited internal_error

POST/v1/posts/{id}/submit

Send an unscheduled post to review

Needs a write key. Role action: post.create.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: unauthorized forbidden not_found rate_limited internal_error

POST/v1/posts/import-csv

Schedule up to 500 posts from a spreadsheet

Send the file as text in csv. The header row names the columns: text (required), accounts (account ids, handles or platform names separated by ; or |), scheduled_at (2026-11-02T15:00; no offset is read in the workspace time zone, a Z or +02:00 is exact) or date and time (read in the workspace time zone), media_urls, and link (added to the end of the text). A row without a time is saved as an unscheduled post. A file whose columns are named differently says which is which in columns. Every row is checked against its destinations exactly as a post made by hand: with the default on_error: "abort" nothing is queued if any row is refused, with "skip" the rows that pass are queued. dry_run: true checks everything and keeps nothing (files are not fetched). Files at media_urls are brought into the library (up to 25 different addresses). Publer files import as they are (a Date column holding 2026/11/02 15:00, a Media URL column separated by commas, a Link column), and so do SocialBee files (text, imageUrls, gifUrls, videoUrls, postAtSpecificTime). Hootsuite files have no header row: add the header row scheduled_at,text,link and write the dates as 2026-11-20 09:30. Send an Idempotency-Key to repeat an import safely for 24 hours: the same file returns the posts it made, another file with the same key is a 409.

Needs a write key. Role action: post.create.

Parameter	In	Type	Required
`Idempotency-Key`	header	string	No

Body field	Type	Required
`csv`	string	Yes
`columns`	object	No
`default_account_ids`	string[]	No
`on_error`	"abort" \| "skip"	No
`dry_run`	boolean	No

Errors: rows invalid_input unauthorized plan_limit forbidden conflict queued committed rate_limited internal_error provider_unavailable

DELETE/v1/review-links/{id}

Turn a review link off

The link stops working at once for the client. Only the person who made it, an admin or the owner can revoke it.

Needs a write key. Role action: reviewlink.create.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: revoked unauthorized forbidden not_found rate_limited internal_error

Media

GET/v1/media

List the media library by name, type and library flag

Needs a read key. Role action: read.

Parameter	In	Type	Required
`limit`	query	string	No
`cursor`	query	string	No
`q`	query	string	No
`kind`	query	"image" \| "gif" \| "video" \| "audio" \| "document"	No
`library`	query	"true" \| "false"	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

POST/v1/media

Import a file from a public address

The address is fetched through the public-address-only fetch: private, loopback and link-local addresses are refused. Until the file is fetched its size is unknown, so the import holds room for the largest file the plan takes and the fetch stops there; to use a file's exact size, upload it instead.

Needs a write key. Role action: library.edit.

Body field	Type	Required
`url`	string	Yes
`name`	string	No
`in_library`	boolean	No

Errors: invalid_input unauthorized plan_limit forbidden rate_limited internal_error media_storage_full

POST/v1/media/uploads

Get a resumable signed upload address and the media id

Upload the file to upload_url with the headers returned, directly to storage (a request body over 4.5 MB never reaches this server). When those headers include tus-resumable, run a TUS 1.0.0 upload: a POST with Upload-Length set to the file size to open it, then PATCH requests of 6 MB each (the last one shorter) to the Location it returns, sending the returned x-signature header on every request. Otherwise send the whole file in one request using method. The size is checked against the plan before the address is made, and the room is held until the address expires. A stored file larger than the declared bytes is deleted when it lands and makes no media.

Needs a write key. Role action: library.edit.

Body field	Type	Required
`name`	string	Yes
`mime`	string	Yes
`bytes`	integer	Yes
`in_library`	boolean	No

Errors: invalid_input unauthorized allowance_used plan_limit forbidden rate_limited internal_error media_storage_full

Accounts

GET/v1/accounts

The connected accounts, with their state

Never carries a token, password, webhook address or signing secret, whatever the role.

Needs a read key. Role action: read.

Errors: unauthorized forbidden rate_limited internal_error

GET/v1/accounts/{id}

One connected account

Needs a read key. Role action: read.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: unauthorized forbidden not_found rate_limited internal_error

PATCH/v1/accounts/{id}

Disable or enable an account, or change its settings

Disabling keeps the account's history and frees a slot of the plan; enabling again needs no reconnect while the connection is still valid.

Needs a write key. Role action: workspace.manage.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`disabled`	boolean	No
`settings`	object	No

Errors: invalid_input unauthorized forbidden not_found rate_limited internal_error

DELETE/v1/accounts/{id}

Disconnect an account: its tokens are erased and its queued posts are canceled

The account keeps its history and shows as disabled. Posts already live on the platform are not touched.

Needs a write key. Role action: workspace.manage.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: disconnected unauthorized forbidden not_found rate_limited internal_error

PATCH/v1/accounts/{id}/name

Give an account your own name; the platform's name is kept

Send name: null to go back to the platform's name.

Needs a write key. Role action: workspace.manage.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`name`	string or null	Yes

Errors: invalid_input unauthorized forbidden not_found rate_limited internal_error

POST/v1/accounts/{id}/pick

Pick the Page, channel, blog or location an account posts to

Needs a write key. Role action: workspace.manage.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`target_id`	string	Yes

Errors: invalid_input unauthorized forbidden not_found rate_limited internal_error provider_unavailable

POST/v1/accounts/{id}/reconnect-link

Make a link a client opens to connect one broken account again

No 1Post login is needed and scheduled posts stay. It works for this account only, once, for 7 days. Only for an account that is waiting to be reconnected and connects by redirect. The link is in this response only.

Needs a write key. Role action: workspace.manage.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: unauthorized forbidden not_found rate_limited internal_error

GET/v1/accounts/{id}/targets

The Pages, boards, playlists, locations or blogs an account can post to, and the one picked

Needs a read key. Role action: read.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: unauthorized forbidden not_found rate_limited internal_error provider_unavailable

POST/v1/accounts/connect

Get the address that connects an account by redirect

Open authorize_url in a browser signed in to the platform. The platform sends the person back to this API's callback and then to the site. The key API form of an invite link.

Needs a write key. Role action: workspace.manage.

Body field	Type	Required
`platform`	string (one of a fixed list)	Yes
`instance`	string	No
`account_id`	string	No

Errors: invalid_input unauthorized account_limit forbidden rate_limited internal_error provider_unavailable

POST/v1/accounts/connect/form

Connect an account that uses a password, token or pasted address

For Bluesky (app password), Telegram, Discord, Slack, a webhook address, WordPress, DEV, Hashnode, Lemmy and X with your own keys. The details are checked with the platform, sealed and never shown again.

Needs a write key. Role action: workspace.manage.

Body field	Type	Required
`platform`	string (one of a fixed list)	Yes
`fields`	object	Yes

Errors: invalid_input unauthorized account_limit forbidden rate_limited internal_error provider_unavailable

POST/v1/invite-links

Make an expiring link a client opens to connect their own account into this workspace

No 1Post login is needed. Only platforms that connect by redirect are offered; the token is in this response only.

Needs a write key. Role action: workspace.manage.

Body field	Type	Required
`platform`	string (one of a fixed list) or null	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

Slots

GET/v1/slots

The weekly slots, in the workspace time zone

Needs a read key. Role action: read.

Errors: unauthorized forbidden rate_limited internal_error

POST/v1/slots

Add a weekly slot

Needs a write key. Role action: library.edit.

Body field	Type	Required
`weekday`	integer	Yes
`minute`	integer	Yes
`account_ids`	string[]	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

PATCH/v1/slots/{id}

Change a slot that no future post uses

Needs a write key. Role action: library.edit.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`weekday`	integer	No
`minute`	integer	No
`account_ids`	string[]	No

Errors: invalid_input unauthorized forbidden not_found rate_limited internal_error

DELETE/v1/slots/{id}

Delete a slot, optionally moving the posts that use it to the next free slot

Needs a write key. Role action: library.edit.

Parameter	In	Type	Required
`id`	path	string	Yes
`move_to`	query	"next_free_slot"	No

Errors: deleted invalid_input unauthorized forbidden not_found rate_limited internal_error

POST/v1/slots/next

The next free slot for some accounts

Nothing is booked. No free slot is an error, never an immediate publish.

Needs a write key. Role action: post.create.

Body field	Type	Required
`account_ids`	string[]	Yes

Errors: invalid_input unauthorized forbidden no_free_slot rate_limited internal_error

Library

GET/v1/sets

Saved selections of accounts and their platform settings

Needs a read key. Role action: read.

Errors: unauthorized forbidden rate_limited internal_error

POST/v1/sets

Save a set of accounts and settings

Needs a write key. Role action: library.edit.

Body field	Type	Required
`name`	string	Yes
`account_ids`	string[]	Yes
`settings`	object	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

PATCH/v1/sets/{id}

Change a set

Needs a write key. Role action: library.edit.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`name`	string	No
`account_ids`	string[]	No
`settings`	object	No

Errors: updated invalid_input unauthorized forbidden not_found rate_limited internal_error

DELETE/v1/sets/{id}

Delete a set

Needs a write key. Role action: library.edit.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: deleted unauthorized forbidden not_found rate_limited internal_error

GET/v1/signatures

Saved blocks of text added to posts

Needs a read key. Role action: read.

Errors: unauthorized forbidden rate_limited internal_error

POST/v1/signatures

Save a signature

Needs a write key. Role action: library.edit.

Body field	Type	Required
`name`	string	Yes
`text`	string	Yes
`auto_add`	boolean	No
`platforms`	string (one of a fixed list)[] or null	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

PATCH/v1/signatures/{id}

Change a signature

Needs a write key. Role action: library.edit.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`name`	string	No
`text`	string	No
`auto_add`	boolean	No
`platforms`	string (one of a fixed list)[] or null	No

Errors: updated invalid_input unauthorized forbidden not_found rate_limited internal_error

DELETE/v1/signatures/{id}

Delete a signature

Needs a write key. Role action: library.edit.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: deleted unauthorized forbidden not_found rate_limited internal_error

GET/v1/tags

Tags with their colors

Needs a read key. Role action: read.

Errors: unauthorized forbidden rate_limited internal_error

POST/v1/tags

Make a tag

Needs a write key. Role action: library.edit.

Body field	Type	Required
`name`	string	Yes
`color`	string	Yes

Errors: invalid_input unauthorized forbidden rate_limited internal_error

PATCH/v1/tags/{id}

Rename or recolor a tag

Needs a write key. Role action: library.edit.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`name`	string	No
`color`	string	No

Errors: updated invalid_input unauthorized forbidden not_found rate_limited internal_error

DELETE/v1/tags/{id}

Delete a tag

Needs a write key. Role action: library.edit.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: deleted unauthorized forbidden not_found rate_limited internal_error

Webhooks

GET/v1/webhooks

Outgoing webhook endpoints

Owners and admins only: an address can carry a secret of its own. The signing secret is never listed.

Needs a read key. Role action: webhooks.manage.

Errors: unauthorized forbidden rate_limited internal_error

POST/v1/webhooks

Add a webhook endpoint

The address must be public and use https. The signing secret (Standard Webhooks, whsec_) is in this response only.

Needs a write key. Role action: webhooks.manage.

Body field	Type	Required
`url`	string	Yes
`events`	string (one of a fixed list)[]	Yes
`account_ids`	string[] or null	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

PATCH/v1/webhooks/{id}

Change the events or scope of a webhook, or switch it on or off

Needs a write key. Role action: webhooks.manage.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`events`	string (one of a fixed list)[]	No
`account_ids`	string[] or null	No
`enabled`	boolean	No

Errors: updated invalid_input unauthorized forbidden not_found rate_limited internal_error

DELETE/v1/webhooks/{id}

Delete a webhook endpoint

Needs a write key. Role action: webhooks.manage.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: deleted unauthorized forbidden not_found rate_limited internal_error

POST/v1/webhooks/{id}/test

Send a signed test event now

Needs a write key. Role action: webhooks.manage.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: unauthorized forbidden not_found rate_limited internal_error provider_unavailable

Analytics

GET/v1/analytics/export

The posts of a range with their latest numbers, as CSV text

One row per post, newest first, up to 5,000 rows, with one column per metric. Posts imported from the account's own history are marked "published elsewhere". Cells that would run as a formula in a spreadsheet are written as text. Stored numbers only.

Needs a read key. Role action: read.

Parameter	In	Type	Required
`range`	query	"7d" \| "30d" \| "all"	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

GET/v1/analytics/refresh

How many on-demand refreshes are left today

Needs a read key. Role action: read.

Errors: unauthorized forbidden rate_limited internal_error

POST/v1/analytics/refresh

Ask for fresh numbers for one published post

Read at the next collector run. 5 a day per workspace for most destinations, 50 a day on Bluesky and Mastodon, and never on X. Asking again while one is waiting costs nothing.

Needs a write key. Role action: post.create.

Body field	Type	Required
`post_id`	string	Yes
`account_id`	string	Yes

Errors: invalid_input unauthorized plan_limit forbidden rate_limited internal_error

GET/v1/analytics/summary

Totals per platform, the best posts, and account cards compared with the previous period

Reads stored snapshots only; nothing is fetched from a platform on demand.

Needs a read key. Role action: read.

Parameter	In	Type	Required
`range`	query	"7d" \| "30d" \| "all"	No
`account_id`	query	string	No
`days`	query	"7" \| "30" \| "90"	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

GET/v1/imported-posts

Posts imported from an account's own history (published elsewhere)

Up to 90 days back, read when the account was connected. They feed analytics and cannot be scheduled, edited or published again.

Needs a read key. Role action: read.

Parameter	In	Type	Required
`limit`	query	string	No
`cursor`	query	string	No
`account_id`	query	string	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

GET/v1/posts/{id}/analytics

The stored metric snapshots of each destination of a post

Needs a read key. Role action: read.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: unauthorized forbidden not_found rate_limited internal_error

Inbox

GET/v1/comments

Comments and replies gathered from the accounts

Needs a read key. Role action: read.

Parameter	In	Type	Required
`limit`	query	string	No
`cursor`	query	string	No
`status`	query	"open" \| "done" \| "hidden"	No
`account_id`	query	string	No
`post_id`	query	string	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

PATCH/v1/comments/{id}

Set a comment open, done or hidden, or assign it to a member

Needs a write key. Role action: post.comment.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`status`	"open" \| "done" \| "hidden"	No
`assigned_to`	string or null	No

Errors: invalid_input unauthorized forbidden not_found rate_limited internal_error

GET/v1/comments/{id}/labels

The labels on one comment

Needs a read key. Role action: read.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: unauthorized forbidden not_found rate_limited internal_error

POST/v1/comments/{id}/labels

Set the labels on a comment (replaces the ones it had)

Send label_ids: [] to clear them. Up to 10 labels, all from this workspace.

Needs a write key. Role action: post.comment.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`label_ids`	string[]	Yes

Errors: invalid_input unauthorized forbidden not_found rate_limited internal_error

POST/v1/comments/{id}/reply

Send your own reply to a comment, from the account it was left on

The reply goes out at once on the platform, so it needs a role that publishes and confirm: true. 1Post never replies on its own.

Needs a write key. Role action: post.publish.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`text`	string	Yes
`confirm`	boolean	Yes

Errors: invalid_input unauthorized forbidden not_found rate_limited internal_error provider_unavailable

GET/v1/inbox-labels

The labels the team sorts the inbox with

Needs a read key. Role action: read.

Errors: unauthorized forbidden rate_limited internal_error

POST/v1/inbox-labels

Add an inbox label

Needs a write key. Role action: library.edit.

Body field	Type	Required
`name`	string	Yes
`color`	string	Yes

Errors: invalid_input unauthorized forbidden rate_limited internal_error

PATCH/v1/inbox-labels/{id}

Rename or recolor an inbox label

Needs a write key. Role action: library.edit.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`name`	string	No
`color`	string	No

Errors: updated invalid_input unauthorized forbidden not_found rate_limited internal_error

DELETE/v1/inbox-labels/{id}

Delete an inbox label; it comes off every item

Needs a write key. Role action: library.edit.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: deleted unauthorized forbidden not_found rate_limited internal_error

GET/v1/inbox-labels/{id}/comments

The ids of the comments that carry a label, newest first

Needs a read key. Role action: read.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: unauthorized forbidden not_found rate_limited internal_error

Automation

GET/v1/plugs

Rules that act on a post when it reaches a like count

Needs a read key. Role action: read.

Errors: unauthorized forbidden rate_limited internal_error

POST/v1/plugs

Save a plug, off

A plug repeats or answers with fixed text you wrote; it calls no model. Switch it on with PATCH.

Needs a write key. Role action: automation.manage.

Body field	Type	Required
`scope`	"connection" \| "post"	Yes
`account_id`	string	No
`post_id`	string	No
`kind`	"repost" \| "follow_up" \| "cross_comment" \| "cross_repost"	Yes
`threshold_likes`	integer	Yes
`text`	string	No
`helper_account_ids`	string[]	No
`delay_min`	integer	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

PATCH/v1/plugs/{id}

Switch a plug on or off

Needs a write key. Role action: automation.manage.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`enabled`	boolean	Yes

Errors: invalid_input unauthorized forbidden not_found rate_limited internal_error

DELETE/v1/plugs/{id}

Delete a plug

Needs a write key. Role action: automation.manage.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: deleted unauthorized forbidden not_found rate_limited internal_error

Account

GET/v1/audit

The workspace audit trail: what was done, by a member, a key, an MCP client or a rule

Needs a read key. Role action: workspace.manage.

Parameter	In	Type	Required
`limit`	query	string	No
`cursor`	query	string	No
`action`	query	string	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

GET/v1/me

The workspace, the role this key or sign-in acts with, and the plan

Needs a read key. Role action: read.

Errors: unauthorized forbidden rate_limited internal_error

GET/v1/notifications

The notification center for the member this key acts as, newest first

Needs a read key. Role action: read.

Parameter	In	Type	Required
`limit`	query	string	No
`cursor`	query	string	No
`unread`	query	"true" \| "false"	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

POST/v1/notifications/preferences

Turn the email for one kind of notice on or off

Needs a write key. Role action: read.

Body field	Type	Required
`kind`	string	Yes
`email`	boolean	Yes

Errors: invalid_input unauthorized forbidden rate_limited internal_error

POST/v1/notifications/read

Mark notifications read, some by id or all

Needs a write key. Role action: read.

Body field	Type	Required
`ids`	string[]	No
`all`	boolean	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

GET/v1/usage

Plan limits and what this month has used of each allowance

Needs a read key. Role action: read.

Errors: unauthorized forbidden rate_limited internal_error

Connect links

GET/v1/connect-links/{token}

What an invite link is for: the workspace name and the platforms it offers

No key needed.

Parameter	In	Type	Required
`token`	path	string	Yes

Errors: rate_limited internal_error

POST/v1/connect-links/{token}/start

A client begins connecting their own account with an invite link

No key needed.

Parameter	In	Type	Required
`token`	path	string	Yes

Errors: rate_limited internal_error

GET/v1/connect/{platform}/callback

Where a platform sends the person back; answers with a redirect to the site

No key needed.

Parameter	In	Type	Required
`platform`	path	string	Yes

Errors: rate_limited internal_error

Free tools

GET/v1/public/tools/{tool}

Run a free tool (check_post, split_thread, platform_limits, build_utm_link) with query parameters

30 requests a minute and 1,000 a day per address. No key.

No key needed.

Parameter	In	Type	Required
`tool`	path	string	Yes

Errors: rate_limited internal_error

POST/v1/public/tools/{tool}

Run a free tool with a JSON body (for long text)

No key needed.

Parameter	In	Type	Required
`tool`	path	string	Yes

Errors: rate_limited internal_error

MCP

GET/.well-known/oauth-authorization-server

RFC 8414 authorization server metadata

No key needed.

Errors: rate_limited internal_error

GET/.well-known/oauth-protected-resource

RFC 9728 metadata for the MCP resource

No key needed.

Errors: rate_limited internal_error

GET/.well-known/oauth-protected-resource/v1/mcp

RFC 9728 metadata for /v1/mcp

No key needed.

Errors: rate_limited internal_error

GET/.well-known/oauth-protected-resource/v1/mcp/oauth

RFC 9728 metadata for /v1/mcp/oauth

No key needed.

Errors: rate_limited internal_error

POST/oauth/register

RFC 7591 dynamic registration of a public client

No key needed.

Errors: rate_limited internal_error

POST/oauth/revoke

RFC 7009 revocation

No key needed.

Errors: rate_limited internal_error

POST/oauth/token

Authorization code and refresh token grants

No key needed.

Errors: rate_limited internal_error

POST/v1/mcp

The MCP server: free tools with no credential, every tool with a key or an OAuth token

No key needed.

Errors: rate_limited internal_error

POST/v1/mcp/oauth

The same MCP server at an address that requires an OAuth sign-in

No key needed.

Errors: rate_limited internal_error

Alerts

GET/v1/alert-target

Where failure alerts go (a Slack or Discord channel)

The host and the state only; the webhook address is a secret and is never shown again.

Needs a read key. Role action: webhooks.manage.

Errors: target unauthorized forbidden rate_limited internal_error

POST/v1/alert-target

Send failure alerts to a Slack or Discord channel

Paste an incoming webhook address from Slack (hooks.slack.com/services/...) or a Discord channel webhook (discord.com/api/webhooks/...). You are told when a post fails, may or may not have gone out, is missed, or an account needs to be connected again. Replaces any earlier target.

Needs a write key. Role action: webhooks.manage.

Body field	Type	Required
`url`	string	Yes

Errors: invalid_input unauthorized forbidden rate_limited internal_error

PATCH/v1/alert-target

Switch failure alerts on or off

Needs a write key. Role action: webhooks.manage.

Body field	Type	Required
`enabled`	boolean	Yes

Errors: invalid_input unauthorized forbidden rate_limited internal_error

DELETE/v1/alert-target

Remove the failure-alert target

Needs a write key. Role action: webhooks.manage.

Errors: removed unauthorized forbidden rate_limited internal_error

Brand kits

GET/v1/brand-kits

The workspace's brand kits: name, website, colors, fonts and library assets

Needs a read key. Role action: read.

Errors: unauthorized forbidden rate_limited internal_error

POST/v1/brand-kits

Add a brand kit

The first kit is the primary. Every asset must be in this workspace's media library.

Needs a write key. Role action: library.edit.

Body field	Type	Required
`name`	string	Yes
`is_primary`	boolean	No
`website`	string or null	No
`colors`	string[]	No
`fonts`	string[]	No
`asset_ids`	string[]	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

PATCH/v1/brand-kits/{id}

Change a brand kit, or make it the primary

Needs a write key. Role action: library.edit.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`name`	string	No
`is_primary`	boolean	No
`website`	string or null	No
`colors`	string[]	No
`fonts`	string[]	No
`asset_ids`	string[]	No

Errors: updated invalid_input unauthorized forbidden not_found rate_limited internal_error

DELETE/v1/brand-kits/{id}

Delete a brand kit; another becomes the primary if this one was

Needs a write key. Role action: library.edit.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: deleted unauthorized forbidden not_found rate_limited internal_error

Calendar

GET/v1/calendar/links

The read-only calendar links of this workspace

Never the link itself: it was shown once, when it was made.

Needs a read key. Role action: workspace.manage.

Errors: unauthorized forbidden rate_limited internal_error

POST/v1/calendar/links

Make a read-only link a client opens to see the calendar

No sign-in. It shows when each post goes out, where, a short preview and the calendar notes, and changes nothing. It lasts 30 days unless you set ttl_days (up to 90). The link is in this response only.

Needs a write key. Role action: workspace.manage.

Body field	Type	Required
`ttl_days`	integer	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

DELETE/v1/calendar/links/{id}

Revoke a calendar link at once

Needs a write key. Role action: workspace.manage.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: revoked unauthorized forbidden not_found rate_limited internal_error

GET/v1/calendar/notes

The notes on a date or range of dates

Needs a read key. Role action: read.

Parameter	In	Type	Required
`from`	query	string	Yes
`to`	query	string	Yes

Errors: invalid_input unauthorized forbidden rate_limited internal_error

POST/v1/calendar/notes

Add a note to a date or range of dates

A launch, a holiday, "client away". Up to 500 characters and up to 62 days.

Needs a write key. Role action: post.create.

Body field	Type	Required
`starts_on`	string	Yes
`ends_on`	string	No
`text`	string	Yes

Errors: invalid_input unauthorized forbidden rate_limited internal_error

PATCH/v1/calendar/notes/{id}

Change a calendar note

You can change your own; members who edit the library can change any. Sending starts_on without ends_on makes it a one-day note.

Needs a write key. Role action: post.create.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`starts_on`	string	No
`ends_on`	string	No
`text`	string	No

Errors: updated invalid_input unauthorized forbidden not_found rate_limited internal_error

DELETE/v1/calendar/notes/{id}

Delete a calendar note

Needs a write key. Role action: post.create.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: deleted unauthorized forbidden not_found rate_limited internal_error

Calendar links

GET/v1/calendar-links/{token}

A read-only calendar a team shared: when each post goes out, where, a short preview and the calendar notes

No key and no sign-in: the token in the link is the credential. from and to (ISO 8601) pick the window, up to 100 days; without them it shows the last 7 days and the 5 weeks after. A revoked or expired link answers 409. Limited per address like every public route.

No key needed.

Parameter	In	Type	Required
`token`	path	string	Yes

Errors: rate_limited internal_error

Developer

GET/v1/logs

The last 7 days of API requests for this workspace, with payloads and answers

For owners and admins. Tokens, passwords, keys, signing secrets, authorization headers and chat webhook addresses are replaced with [masked] before they are stored, and each payload is cut to 2,000 characters.

Needs a read key. Role action: apikeys.manage.

Parameter	In	Type	Required
`limit`	query	string	No
`cursor`	query	string	No
`status`	query	string	No
`method`	query	string (one of a fixed list)	No
`key_id`	query	string	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

Feeds

GET/v1/feeds

The RSS feeds that turn new items into posts

For members who can publish: a feed address can carry a private token.

Needs a read key. Role action: automation.manage.

Errors: unauthorized forbidden rate_limited internal_error

POST/v1/feeds

Turn each new item of a feed into a post

New items become unscheduled posts. Queueing them is an opt-in (mode: "queue") that needs a daily_cap you choose. The text is a template you write with {title} and {link}; nothing is written for you.

Needs a write key. Role action: automation.manage.

Body field	Type	Required
`url`	string	Yes
`template`	string	Yes
`account_ids`	string[]	Yes
`mode`	string (one of a fixed list)	No
`post_when`	"next_slot" \| "immediate"	No
`daily_cap`	integer	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

PATCH/v1/feeds/{id}

Change a feed, or switch it on or off

Needs a write key. Role action: automation.manage.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`active`	boolean	No
`mode`	string (one of a fixed list)	No
`post_when`	"next_slot" \| "immediate"	No
`template`	string	No
`daily_cap`	integer	No
`account_ids`	string[]	No

Errors: updated invalid_input unauthorized forbidden not_found rate_limited internal_error

DELETE/v1/feeds/{id}

Delete a feed; posts already made from it stay

Needs a write key. Role action: automation.manage.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: deleted unauthorized forbidden not_found rate_limited internal_error

Members

GET/v1/members

The people in the workspace and their roles

Member references (provider:subject) and roles, never an email address. Use a reference as assigned_to on a comment. Any role may read it, with a key or in the dashboard.

Needs a read key. Role action: read.

Errors: unauthorized forbidden rate_limited internal_error

Recurring

GET/v1/recurring

The posts that repeat, with their next run

Needs a read key. Role action: read.

Errors: unauthorized forbidden rate_limited internal_error

POST/v1/recurring

Make a scheduled post repeat every 1 to 31 days

The post needs a time. A post going to X needs at least two versions of the text in rotation, because X refuses repeats. Each run is written ahead as an ordinary post you can see, edit or cancel.

Needs a write key. Role action: automation.manage.

Body field	Type	Required
`post_id`	string	Yes
`every_days`	integer	Yes
`rotation`	string[]	No
`max_runs`	integer or null	No
`ends_at`	string or null	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

PATCH/v1/recurring/{id}

Change a repeating post for the next run only, or for every run after it

scope is required. The schedule, the rotation and the end change for all future runs; the text can change for the next run or all of them.

Needs a write key. Role action: automation.manage.

Parameter	In	Type	Required
`id`	path	string	Yes

Body field	Type	Required
`scope`	"this_run" \| "all_future"	Yes
`every_days`	integer	No
`rotation`	string[]	No
`max_runs`	integer or null	No
`ends_at`	string or null	No
`parts`	object[]	No

Errors: updated invalid_input unauthorized forbidden not_found rate_limited internal_error

DELETE/v1/recurring/{id}

Stop a repeating post; runs already written stay

Needs a write key. Role action: automation.manage.

Parameter	In	Type	Required
`id`	path	string	Yes

Errors: stopped unauthorized forbidden not_found rate_limited internal_error

Review links

GET/v1/review/{token}

What a client sees on a review link: each post as it will go out, per destination, and the comments so far

The link works without a 1Post login until it expires (7 days unless the maker chose up to 30) or is turned off.

No key needed.

Parameter	In	Type	Required
`token`	path	string	Yes

Errors: forbidden not_found conflict rate_limited internal_error

POST/v1/review/{token}/comments

A client leaves a comment on a post of the link

Limited to 10 writes an address and 30 a link in ten minutes. The website field is a trap for form-filling bots and must be left empty. Sending the same comment again within a minute returns the first one.

No key needed.

Parameter	In	Type	Required
`token`	path	string	Yes

Body field	Type	Required
`post_id`	string	Yes
`author_name`	string	Yes
`text`	string	Yes
`website`	string	No

Errors: invalid_input forbidden not_found conflict rate_limited internal_error

POST/v1/review/{token}/decisions

A client approves a post waiting in review, or asks for changes with a note

No key needed.

Parameter	In	Type	Required
`token`	path	string	Yes

Body field	Type	Required
`post_id`	string	Yes
`author_name`	string	Yes
`decision`	"approve" \| "changes"	Yes
`text`	string	No
`website`	string	No

Errors: invalid_input forbidden not_found conflict rate_limited internal_error

Workspace

GET/v1/utm-preset

The UTM preset added to links when posts go out

Needs a read key. Role action: read.

Errors: preset unauthorized forbidden rate_limited internal_error

POST/v1/utm-preset

Set the UTM preset

When enabled, each link in a post gets utm_source set to the destination (or the name you give it in sources), utm_medium, and the campaign, content and term you set, at publish time. A link that already has a utm_ parameter is left as you wrote it.

Needs a write key. Role action: workspace.manage.

Body field	Type	Required
`enabled`	boolean	Yes
`medium`	string	No
`campaign`	string or null	No
`content`	string or null	No
`term`	string or null	No
`sources`	object	No

Errors: invalid_input unauthorized forbidden rate_limited internal_error

DELETE/v1/utm-preset

Remove the UTM preset

Needs a write key. Role action: workspace.manage.

Errors: preset unauthorized forbidden rate_limited internal_error

Questions

Where is the OpenAPI document?

The API serves OpenAPI 3.1 at /openapi.json on its own host, generated from the same route table as this page.

Does every route need a key?

Every route except the free tools and the invite-link routes needs a key. The Needs column says which.

From one post to every feed

Plan the week in one sitting, keep your team in the loop, and let 1Post publish on time while you get on with the rest of your day.

Start a 7-day trial for $1 See pricing