Create Post

POST

posts

curl --request POST \
  --url https://api.postiz.com/public/v1/posts \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": {
        "id": "your-integration-id"
      },
      "value": [
        {
          "content": "Hello world!",
          "image": []
        }
      ],
      "settings": {
        "__type": "bluesky"
      }
    }
  ]
}
'

[
  {
    "postId": "post-123",
    "integration": "integration-456"
  }
]

Post type: `now`, `schedule`, or `draft`

The top-level type field controls when (and whether) the post is published:

Value	Behaviour
`"now"`	Publish immediately. `date` is ignored.
`"schedule"`	Publish at the time given in `date` (ISO 8601).
`"draft"`	Save as a draft. The post is created and stored against the integration but not scheduled or published. You can promote it to a real post later from the Postiz UI.

Drafts are how you stage content via the API without committing to a publish time, useful for content review workflows or pre-filling a calendar from an external CMS.

Duplicating a post

There is no dedicated duplicate / clone endpoint. To copy an existing post, fetch it with GET /posts and submit the content as a new POST /posts request. Before re-submitting, strip the server-managed fields from the fetched object, re-sending them either causes validation errors or, worse, accidentally updates the original. At minimum drop:

id and any nested post IDs
createdAt, updatedAt, and any other timestamps
state / status / releaseId (these are assigned by the scheduler)
Anything else the API didn’t ask you to provide when you originally created the post

Then set a fresh type (now, schedule, or draft) and date, and POST the cleaned object.

Image alt text (`alt`)

Each media object in a post’s image array accepts an optional alt field: a text description of the image for accessibility.

{
  "image": [{ "id": "img-123", "path": "https://uploads.postiz.com/sunset.jpg", "alt": "A sunset over the sea" }]
}

Providers that support alt text (Instagram, Instagram Standalone, Bluesky, Mastodon, Slack, Tumblr) send it with the image; other providers ignore the field. Instagram applies it to images only (single images and carousel items, up to 1000 characters), not to videos or stories.

Video cover frame (`thumbnailTimestamp`)

Each media object in a post’s image array accepts an optional thumbnailTimestamp field: the number of milliseconds into the video to use as the cover/thumbnail frame.

{
  "image": [{ "id": "vid-123", "path": "https://uploads.postiz.com/video.mp4", "thumbnailTimestamp": 3000 }]
}

Supported providers: Instagram, Instagram Standalone, TikTok Business, and TikTok (Direct Post only: the UPLOAD/inbox flow does not support cover selection). Other providers ignore the field. For TikTok, in our testing the cover was applied only to public posts (privacy_level: "PUBLIC_TO_EVERYONE"); posts published with a restricted privacy level kept the first frame as the cover.

Provider-Specific Settings

When creating posts, each social media platform requires different settings. The settings object must include a __type field that identifies the platform.

All 27 Supported Platforms

Platform	`__type`	Required Settings
X (Twitter)	`x`	`who_can_reply_post` (optional: `community`, `made_with_ai`, `paid_partnership`)
LinkedIn	`linkedin`	-
LinkedIn Page	`linkedin-page`	-
Facebook	`facebook`	- (optional: `url`)
Instagram (FB-linked)	`instagram`	`post_type`
Instagram Standalone	`instagram-standalone`	`post_type`
Threads	`threads`	-
Bluesky	`bluesky`	-
Mastodon	`mastodon`	-
Warpcast (Farcaster)	`warpcast`	- (optional: `subreddit[]` for channels)
Nostr	`nostr`	-
VK	`vk`	-

Platform	`__type`	Required Settings
YouTube	`youtube`	`title`, `type`
TikTok	`tiktok`	`privacy_level`, `duet`, `stitch`, `comment`, `autoAddMusic`, `brand_content_toggle`, `brand_organic_toggle`, `content_posting_method`

TikTok honors these settings only when content_posting_method is DIRECT_POST, with UPLOAD it keeps only the post content/title. duet, stitch, and video_made_with_ai apply to video posts only; autoAddMusic to photo posts only. See TikTok settings.

Platform	`__type`	Required Settings
Reddit	`reddit`	`subreddit[]` (array)
Lemmy	`lemmy`	`subreddit[]` (array)
Discord	`discord`	`channel`
Slack	`slack`	`channel`
Telegram	`telegram`	-

Platform	`__type`	Required Settings
Pinterest	`pinterest`	`board`
Dribbble	`dribbble`	`title`

Platform	`__type`	Required Settings
Medium	`medium`	`title`, `subtitle`
Dev.to	`devto`	`title`
Hashnode	`hashnode`	`title`, `tags[]`
WordPress	`wordpress`	`title`, `type`

Platform	`__type`	Required Settings
Google My Business	`gmb`	- (optional: `topicType`, `callToActionType`)
Listmonk (Newsletters)	`listmonk`	`subject`, `preview`, `list`

Platforms Without Custom Settings

These platforms only need the __type field:

{
  "settings": {
    "__type": "threads"
  }
}

Platforms: threads, mastodon, bluesky, telegram, nostr, vk

Detailed Provider Settings

See the Provider Settings section for detailed schemas and examples for each platform.

Authorizations

Authorization

string

header

required

Your Postiz API key

Body

application/json

type

enum<string>

required

Post type

Available options:

draft,

schedule,

now

date

string<date-time>

required

Publish date in UTC ISO format

shortLink

boolean

required

Whether to use short links

Response

200 - application/json

Post created successfully

postId

string

integration

string

curl --request POST \
  --url https://api.postiz.com/public/v1/posts \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": {
        "id": "your-integration-id"
      },
      "value": [
        {
          "content": "Hello world!",
          "image": []
        }
      ],
      "settings": {
        "__type": "bluesky"
      }
    }
  ]
}
'

[
  {
    "postId": "post-123",
    "integration": "integration-456"
  }
]

Overview

Integrations

Posts

Analytics

Notifications

Uploads

Video Generation

Clipping

Provider settings

Post type: `now`, `schedule`, or `draft`

Duplicating a post

Image alt text (`alt`)

Video cover frame (`thumbnailTimestamp`)

Provider-Specific Settings

All 27 Supported Platforms

Platforms Without Custom Settings

Detailed Provider Settings

Authorizations

Body

Response

Post type: now, schedule, or draft

Duplicating a post

Image alt text (alt)

Video cover frame (thumbnailTimestamp)

Provider-Specific Settings

All 27 Supported Platforms

Platforms Without Custom Settings

Detailed Provider Settings

Authorizations

Body

Response

Post type: `now`, `schedule`, or `draft`

Image alt text (`alt`)

Video cover frame (`thumbnailTimestamp`)