Post modes
POST /api/v1/posts makes a post in one call; mode says what happens to it.
draft
Saves a draft (or a thread). Nothing is published.
{"parts": [{"text": "…"}], "mode": "draft", "connection_ids": ["<connection_id>"]}schedule
Saves it and schedules it for scheduled_at, 2 minutes to 30 days ahead, one delivery per account. No confirmation.
{"parts": [{"text": "…"}], "mode": "schedule", "scheduled_at": "<ISO time 2 min–30 days ahead>", "connection_ids": ["<connection_id>"]}queue
Saves it and puts it in each account's next free posting slot; the answer says when.
{"parts": [{"text": "…"}], "mode": "queue", "connection_ids": ["<connection_id>"]}now
Saves it and answers the preview, the price and a confirmation token (needs_confirmation). Show it to the user; after their yes, publish with POST /api/v1/drafts/{post_id}/publish and the token, never by sending the request again (the resend answers the same draft and a new token). Only a request that already carries the user's yes to this exact post sends "confirm": true the first time, and publishes in one call. With browser approval on, the answer is 202 with an approval_url the user approves in Postory.
{"parts": [{"text": "…"}], "mode": "now", "connection_ids": ["<connection_id>"]}{
"mode": "now",
"status": "needs_confirmation",
"post_id": "<post_id>",
"web_url": "https://postory.io/calendar?view=list&focus=<post_id>",
"draft": {
"id": "<post_id>",
"status": "draft",
"connection_id": "<connection_id>",
"platform": "x"
},
"needs_confirmation": true,
"preflight": {
"ok": true,
"issues": [],
"warnings": [],
"preview": {
"account": {
"connection_id": "<connection_id>",
"platform": "x",
"handle": "yourhandle",
"display_name": "Your Name"
},
"kind": "publish",
"post_id": "<post_id>",
"parts": [
{
"n": 1,
"text": "Shipping v2 today.",
"chars": 18,
"media": 0,
"media_ids": [],
"attachments": []
}
],
"share_with_followers": true
},
"cost": {
"credits_per_delivery": 3,
"direct_publishes": {
"used": 0,
"limit": null,
"reset_at": "2026-12-19T09:00:00+00:00"
},
"account_posts_in_24h": 0,
"account_daily_cap": 30
},
"confirmation_token": "<confirmation_token>",
"approval_required": false,
"approval_status": "needs_chat_yes",
"note": "No approval_url: show the user this preview (account, full text, media) and cost.credits_per_delivery; publish with POST /api/v1/drafts/{post_id}/publish and this confirmation_token only after they explicitly say yes.",
"expires_in": 600
},
"acting_as": {
"postory": "[email protected]",
"x": "yourhandle",
"label": "@yourhandle · X",
"plan": "free"
},
"preview_url": null
}An agent never publishes without the user's yes to that post.