---
title: "Create a post (draft, scheduled, queued, or published now)"
method: POST
path: "/api/posts"
---

# Create a post (draft, scheduled, queued, or published now)

`POST /api/posts`

## Request

- Base URL: `https://octopost.ink`
- URL: `https://octopost.ink/api/posts`
- Auth: HTTP bearer

Draft by default. Set `published: true` to publish now, `scheduledFor` to publish at a time, or `queueStatus` to add it to the interval queue (`pending` waits for approval).

## Request body

- CreatePost
  - `content` string, required: Main post text. X counts links as 23 characters.
  - `platforms` Platform[], required
  - `scheduledFor` string, date-time, nullable: ISO 8601 with a timezone offset.
  - `published` boolean: true = publish now.
  - `queueStatus` 'queued' | 'pending' | 'null', nullable: queued = interval queue; pending = wait for approval.
  - `mediaUrls` Media[]
    - union
      - string, uri
      - object
        - `url` string, uri, required
        - `altText` string
  - `segments` object[]: Thread replies after the main post.
    - `content` string, required
    - `mediaUrls` Media[]
      - union
        - string, uri
        - object
          - `url` string, uri, required
          - `altText` string
  - `poll` object
    - `options` string[]
    - `durationMinutes` integer

## Response `201`

Created. `publishResults` is present when published now.

- object
  - `success` boolean
  - `post` Post
    - `id` string
    - `content` string
    - `platforms` string[]
    - `scheduledFor` string, nullable
    - `published` boolean
    - `queueStatus` string, nullable
    - `platformPostIds` object, nullable: Per network: id, url, or error.
    - `createdAt` string
  - `publishResults` PublishResult[]
    - `platform` string
    - `success` boolean
    - `postUrl` string
    - `error` string: What failed and what to do next.

## Other responses

- `400`: Validation error: the message names the field (for example scheduledFor without a timezone offset, or text over a network limit).
- `401`: Missing or invalid API key. Send `Authorization: Bearer op_...` with the key from https://octopost.ink/dashboard/api-keys.
- `403`: No active plan (finish the $1 trial checkout at https://octopost.ink/dashboard/billing) or the monthly X allowance is used up.
- `429`: Rate limited (per minute per IP; publishing 50/hour). Retry after the `Retry-After` seconds.
- `500`: Server error. Safe to retry; email hello@greatwork.company if it persists.

---

[API](https://skmtc.dev/octopost/apis/octopost-rest-api.md) · [All operations](https://skmtc.dev/octopost/apis/octopost-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/octopost/apis/octopost-rest-api/revisions/87cef7870c1b?raw)