Docs menuPost modes

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.

Body
{"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.

Body
{"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.

Body
{"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.

Body
{"parts": [{"text": "…"}], "mode": "now", "connection_ids": ["<connection_id>"]}
Response 201
{
  "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.