---
title: "Create, schedule, or save a post as a draft for one or more platforms."
method: POST
path: "/v1/posts"
tags: ["posts"]
---

# Create, schedule, or save a post as a draft for one or more platforms.

`POST /v1/posts`

## Request

- Base URL: `https://lovable-anaconda-804.convex.site`
- URL: `https://lovable-anaconda-804.convex.site/v1/posts`
- Auth: HTTP bearer

## Request body

- CreatePostBody
  - `projectId` string, required
  - `text` string, required
  - `platforms` string[], required
  - `idempotency_key` string: Mandatory unless the Idempotency-Key header is sent. Replaying the same key returns the original post.
  - `schedule` object: { kind: 'one_shot', scheduledFor: epoch-ms } or recurring shapes.
  - `save_as_draft` boolean
  - `overrides` object: Per-platform diff over the base: { <platform>: { text?, media? } }.
  - `platform_settings` object: Per-platform publish settings, validated against GET /v1/platforms.
  - `media` MediaItem[]
    - `mediaId` string
    - `kind` 'image' | 'video' | 'gif', required
    - `mimeType` string, required
    - `bytes` number, required
    - `durationMs` number
    - `altText` string: Accessibility description for image/gif media.
    - `aspectRatio` object
      - `width` number
      - `height` number

## Response `200`

Created. status may be 'pending_approval' (held for review by the project's agent policy) with zero legs.

## Other responses

- `401`: Missing or invalid bearer token
- `403`: Scope or account allowlist blocked (DY_KEY_*)
- `422`: Pre-flight validation failed (violations[])
- `429`: Key posts-per-day cap reached (DY_KEY_POST_CAP_EXCEEDED)

---

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