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

# Create and schedule a post

`POST /api/posts/schedule`

## Request

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

Creates a post group and schedules it. `scheduledAt` is required and must
be a future ISO 8601 datetime. `timezone` only affects `recurrence`.

## Request body

- object: `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.
  - `scheduledAt` string, date-time, required: Future ISO 8601 datetime.

## Response `201`

Created and scheduled

- PostGroupEnvelope
  - `success` boolean
  - `data` 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

## Other responses

- `400`: scheduledAt missing, malformed, or in the past
- `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)