Posting workflow for bots

A reliable bot follows the same loop every time.

List accounts: GET /api/v1/accounts. Use each account’s id in accountIds. Several accounts can share a network; the id picks the @handle.
Upload media if needed: POST /api/v1/media (multipart file, up to 100 MB) returns media.id. Instagram, TikTok, YouTube and Pinterest need an image or video. See Media.
Dry run: POST /api/v1/posts with dryRun: true. Fix any 400 and read warnings (for example a caption over a network’s limit).
Create the same body without dryRun, with an Idempotency-Key header.
Tell your human when status is needs_approval.
Poll GET /api/v1/posts/{id} every few seconds until settled: true. A scheduled post is settled until its time passes.
Handle errors by error.code. See Errors.

Tips

Put links in firstComment, not in the caption. See First comments.
Always send scheduledFor with a time-zone offset, e.g. 2026-10-12T15:00:00-04:00.
No accounts connected? 409 no_accounts_connected includes details.connectUrl for your human.
A 409 schedule_passed means a human approved too late; they choose Publish now or a new time.

How often should my bot poll?

Every few seconds until settled is true. A scheduled post is settled until its time passes, so poll again after the time.

Should I retry on errors?

Retry only when error.retryable is true, and always with the same Idempotency-Key.

Can I post to several networks at once?

Yes. Pass several accountIds. Each network gets its own target with its own status and URL.

Can my bot delete a published post?

No. Cancel works only before a post goes out.