Authorization: Bearer <key>. Posts, drafts and analytics need accounts:read, posts:read and posts:write; media.* needs media:read/media:write, workflows.* needs workflows:read/workflows:write. A key without a scope gets a 403 for those calls.
Things to know:
- Accounts are the targets.
accounts.listreturns each connected account’sid,statusandmedia_requirements. Pass the ids astargets[].account_idinposts.create, and only post to accounts whosestatusisactive. Instagram, TikTok, YouTube and Pinterest need at least one image or video. - Now or later.
posts.createwithoutpublish_atpublishes right away. With an ISO-8601publish_atit is scheduled, andposts.cancelstops it before it runs. - Media goes in by URL.
media[].urlmust be an absolute HTTP or HTTPS URL that PostOnce can download when it publishes. - Retries do not double-post. Pass
idempotencyKey(sent as theIdempotency-Keyheader) toposts.create,drafts.createorworkflows.create: a repeat with the same body returns the original. After a 5xx or network error the plugin retries reads only; a write whose reply was lost may already have run, so it is never replayed. - Drafts before posts.
drafts.createsaves text, media and intended accounts without scheduling anything.drafts.updateneeds the draft’s currentupdated_atasexpected_updated_atand returns 409 if it changed since. - Uploading media.
media.createUploadreturns a signed URL and amedia_id. PUT the file’s bytes to the URL, thenmedia.getgives thepublic_urlto use asmedia[].url. - Workflows post on their own. An active workflow copies every new post from its source account to its targets, so
workflows.createandworkflows.updateare destructive. - Webhooks.
webhooks.createregisters an HTTPS endpoint forpost.published,post.partially_publishedandpost.failed; the reply is the only time its signing secret is shown. This plugin does not receive those events yet. - One post, many destinations. A post’s
statussums up itstargets; each target carries its ownstatus,platform_post_urlanderror. - Paging.
posts.listreturns up tolimitposts (default 20, max 100), newest first. Passmeta.next_cursorasafterfor the next page; it is null on the last page.
- 25 typed API operations
- 2 synced entities (
accounts,posts) for fast.search()/.list()
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the PostOnce API key before the first call: More: API Key
pnpm corsair setup --plugin=postonce --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
List connected social accountsQuery synced data
Synced entities supporttenant.postonce.db.<entity>.search() and .list(): accounts, posts.
See Database for filters and operators.
What’s next
API reference
Every
postonce.api.* operation with input and output types.Database
Synced entities, search filters, and operators.
Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.