---
title: "Create a post (schedule, publish now or save a draft)"
method: POST
path: "/v1/posts"
---

# Create a post (schedule, publish now or save a draft)

`POST /v1/posts`

## Request

- Base URL: `https://api.breakreach.com`
- URL: `https://api.breakreach.com/v1/posts`
- Auth: HTTP bearer

Creates a post targeting one or several connected accounts. Provide scheduledAt (interpreted in the workspace timezone), or set useNextSlot to schedule at the next free slot of the workspace posting schedule, or publishNow to publish immediately. Set draft to save it for review in Breakreach without scheduling it: a draft needs no publish time (scheduledAt, if given, places it on the calendar), skips the media checks, and goes out only once it is scheduled, in the app or with PATCH /v1/posts/{id}. Media must be public URLs — use POST /v1/media first for reliable hosting. Media is required for Instagram, TikTok, YouTube and Pinterest. On Instagram one photo is a feed post, one video a Reel, and 2 to 10 files (photos and videos, in order) a carousel whose photos are all cropped to the first photo's shape. Facebook Pages take up to 10 photos in one post, or one video. LinkedIn posts one MP4 video alone, or turns 2 to 20 photos into a carousel (a PDF document, one page per photo, all cropped to the first photo's shape, titled with the first line), and posts a PDF URL as a document. Pinterest takes one image or one MP4/MOV video; an image sent with the video becomes its cover.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `content` string, required: The post text. For Reddit, the first line becomes the title.
  - `accountIds` string[], required: Target account ids from GET /v1/accounts
  - `scheduledAt` string: ISO datetime in the workspace timezone, e.g. 2026-09-20T11:00:00
  - `publishNow` boolean
  - `useNextSlot` boolean
  - `draft` boolean: Save as a draft for review instead of scheduling it. Can't be combined with publishNow
  - `media` string[]
  - `workspace` string: Workspace slug (optional)
  - `pinterestBoardId` string: Required when targeting Pinterest — see GET /v1/pinterest-boards
  - `pinterestLink` string, uri: Destination URL of the pin (optional, http(s), up to 2,048 characters). The pin title is the first line of content
  - `redditSubreddit` string: Subreddit without r/ — defaults to the user profile
  - `redditFlairText` string: Post flair name when the subreddit requires one
  - `articleSettings` ArticleSettings: Options for the blog networks (Dev.to, Hashnode, Ghost, Tumblr). On Dev.to, Hashnode and Ghost the first line of content is the title and the rest the body, in Markdown; the first photo is the cover
    - `tags` string[]: Dev.to keeps the first 4 (letters and digits), Hashnode 15, Ghost and Tumblr up to 30
    - `canonicalUrl` string, uri: Where the article was first published, when this is a copy (Dev.to, Hashnode, Ghost)
    - `asDraft` boolean: Create it as an unpublished draft on the blog instead of publishing it
    - `newsletter` string: Ghost: also email the post with this newsletter (its slug, or "default" for the site's first active one)
    - `emailSegment` 'all' | 'status:free' | 'status:-free': Ghost newsletter: who gets the email (default all members)
    - `aiDisclosure` 'no_ai' | 'some_ai' | 'fully_autonomous': Dev.to: how much AI wrote the article (Dev.to asks API clients to say so accurately)
  - `googleBusinessSettings` GoogleBusinessSettings: Google Business Profile only: the button under the update. The update itself is the content (up to 1,500 characters) and one photo; videos aren't accepted
    - `button` 'BOOK' | 'ORDER' | 'SHOP' | 'LEARN_MORE' | 'SIGN_UP' | 'CALL': BOOK, ORDER (order online), SHOP (buy), LEARN_MORE, SIGN_UP, or CALL (calls the profile's phone number). Omit for no button
    - `buttonUrl` string, uri: Where the button leads (http/https), required for every button except CALL
  - `tiktokSettings` object
    - `privacyLevel` 'PUBLIC_TO_EVERYONE' | 'MUTUAL_FOLLOW_FRIENDS' | 'FOLLOWER_OF_CREATOR' | 'SELF_ONLY'
    - `disableComment` boolean
    - `disableDuet` boolean
    - `disableStitch` boolean

## Response `200`

Created

- object
  - `post` CreatedPost, required
    - `id` string, required
    - `status` 'draft' | 'scheduled' | 'publishing', required: publishing when publishNow was set, draft when draft was set
    - `scheduledAt` string, date-time, required: Publish time, in UTC
    - `accounts` string[], required: Target accounts as "platform (display name)", e.g. "instagram (Acme)"

## Other responses

- `400`: Validation error: missing content, accountIds or publish time, an account outside the workspace, missing media or pinterestBoardId, invalid scheduledAt, pinterestLink or googleBusinessSettings, a Google Business Profile update over 1,500 characters or with a video
- `401`: Missing, invalid or expired API key
- `402`: No active Breakreach subscription or trial
- `403`: Not a member of the requested workspace
- `404`: Workspace not found, or useNextSlot found no free slot
- `409`: A request with this Idempotency-Key is still running: retry after Retry-After seconds to get its response
- `422`: This Idempotency-Key was already used with a different request in the last 24 hours

---

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