---
title: "Create and publish a post now"
method: POST
path: "/api/posts/publish"
tags: ["Posts"]
---

# Create and publish a post now

`POST /api/posts/publish`

## Request

- Base URL: `https://api-app.postnext.io`
- URL: `https://api-app.postnext.io/api/posts/publish`
- Auth: API key in header `x-api-key`

Creates a post group and publishes it immediately to every channel in the
`providers` map. Partial success returns 200 with `publishStatus.partial`
set to true (it is not an error).

## Request body

- CreatePostRequest: `userId` and `teamId` are derived from the API key and must not be sent.
  - `providers` object, required: Map keyed by provider name (for example `twitter`) or `provider:channelHandle` for multi-account posting.
  - `title` string
  - `description` string
  - `imageUrl` string, uri
  - `tags` string[]
  - `assigneeId` string
  - `watchers` string[]
  - `timezone` string: IANA timezone, used with recurrence.
  - `recurrence` object: Optional repeat rule.

## Response `201`

Created and published

- PublishEnvelope
  - `success` boolean
  - `data` object
    - `group` PostGroup
      - `id` string: Post group uuid.
      - `_id` string: Mongo ObjectId.
      - `userId` string
      - `teamId` string
      - `title` string
      - `description` string
      - `imageUrl` string, uri
      - `providers` object
      - `tags` string[]
      - `scheduledTime` string, date-time
      - `status` 'DRAFT' | 'SCHEDULED' | 'PUBLISHING' | 'PUBLISHED' | 'FAILED' | 'APPROVAL'
      - `assigneeId` string
      - `watchers` string[]
      - `createdAt` string, date-time
      - `updatedAt` string, date-time
    - `providerPosts` object[]
    - `publishStatus` object
      - `success` boolean
      - `partial` boolean
      - `successfulPublishes` integer
      - `totalPublishes` integer
      - `failures` object[]

## Other responses

- `400`: Validation failed (thread order/media, first comment over cap `INVALID_FIRST_COMMENT`, or invalid recurrence `INVALID_RECURRENCE`).
- `401`: Missing or invalid API key
- `402`: Subscription is inactive (payment failure). Flat shape, not the standard envelope.
- `403`: Posting not allowed on the current plan, or monthly quota reached

---

[API](https://skmtc.dev/postnext/apis/postnext-public-api.md) · [All operations](https://skmtc.dev/postnext/apis/postnext-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postnext/apis/postnext-public-api/revisions/c0bf3aa03271?raw)