Skip to main content
POST
/
public
/
v1
/
posts
Create Post
curl --request POST \
  --url https://api.example.com/public/v1/posts \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "date": "<string>",
  "shortLink": true,
  "tags": [
    {}
  ],
  "posts": [
    {
      "posts[].integration": {},
      "posts[].value": [
        {}
      ],
      "posts[].settings": {}
    }
  ]
}
'
{
  "400": {},
  "401": {},
  "403": {},
  "id": "<string>",
  "group": "<string>",
  "status": "<string>",
  "publishDate": "<string>"
}

​
Overview

Create and schedule posts to one or more social media platforms. Supports text content, media attachments, comments/threads, and platform-specific settings.

​
Request

​
type
string
required
Post type. One of:
  • schedule - Schedule post for future publication
  • draft - Save as draft
  • now - Publish immediately
  • update - Update existing post
​
date
string
required
ISO 8601 date string for when the post should be published. Required even for drafts.Example: 2024-12-31T12:00:00Z
​
shortLink
boolean
required
Whether to use shortened links in the post content. Defaults to true.
​
tags
array
Array of tag objects for categorizing posts.Each tag object has:
  • value (string) - Tag identifier
  • label (string) - Display label
​
posts
array
required
Array of post objects, one for each integration/platform.

​
Response

​
id
string
Unique identifier for the created post group
​
group
string
Group identifier linking related posts across platforms
​
status
string
Post status: scheduled, draft, published, or failed
​
publishDate
string
ISO 8601 timestamp when the post will be/was published

​
Examples

curl -X POST https://api.postiz.com/public/v1/posts \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "schedule",
    "date": "2024-12-31T12:00:00Z",
    "shortLink": true,
    "tags": [],
    "posts": [
      {
        "integration": {
          "id": "twitter-integration-id"
        },
        "value": [
          {
            "content": "Hello from Postiz API!",
            "image": []
          }
        ]
      }
    ]
  }'

​
Multi-Platform Posting

Post to multiple platforms simultaneously: 
{
  "type": "schedule",
  "date": "2024-12-31T12:00:00Z",
  "shortLink": true,
  "tags": [],
  "posts": [
    {
      "integration": { "id": "twitter-id" },
      "value": [{ "content": "Hello Twitter!", "image": [] }]
    },
    {
      "integration": { "id": "linkedin-id" },
      "value": [{ "content": "Hello LinkedIn!", "image": [] }]
    },
    {
      "integration": { "id": "facebook-id" },
      "value": [{ "content": "Hello Facebook!", "image": [] }]
    }
  ]
}

​
Platform-Specific Settings

​
Reddit Post

{
  "integration": { "id": "reddit-id" },
  "value": [{ "content": "Post content", "image": [] }],
  "settings": {
    "subreddit": [{
      "value": {
        "subreddit": "programming",
        "title": "My Post Title",
        "type": "text",
        "url": "",
        "is_flair_required": false
      }
    }]
  }
}

​
YouTube Video

{
  "integration": { "id": "youtube-id" },
  "value": [{ 
    "content": "Video description",
    "image": [{
      "id": "video1",
      "path": "https://cdn.postiz.com/video.mp4"
    }]
  }],
  "settings": {
    "title": "My Video Title",
    "type": "public",
    "tags": [
      { "value": "tech", "label": "Tech" },
      { "value": "tutorial", "label": "Tutorial" }
    ]
  }
}

​
Twitter/X Reply Settings

{
  "integration": { "id": "twitter-id" },
  "value": [{ "content": "Tweet content", "image": [] }],
  "settings": {
    "who_can_reply_post": "everyone"
  }
}

​
Threads and Comments

Create Twitter threads or post comments by adding multiple items to the value array: 
{
  "integration": { "id": "twitter-id" },
  "value": [
    {
      "content": "1/3 Thread starter...",
      "image": []
    },
    {
      "content": "2/3 Second tweet...",
      "image": [],
      "delay": 2000
    },
    {
      "content": "3/3 Final tweet...",
      "image": [],
      "delay": 2000
    }
  ]
}
The delay property (in milliseconds) controls the time between each post in the thread.

​
Error Responses

​
400
Bad Request
Validation error in request body
{
  "statusCode": 400,
  "message": ["date must be a valid ISO 8601 date string"],
  "error": "Bad Request"
}
​
401
Unauthorized
Invalid or missing API key
{
  "msg": "Invalid API key"
}
​
403
Forbidden
Insufficient permissions or plan limits exceeded
{
  "msg": "Monthly post limit exceeded"
}

​
Notes

The date field is required even for draft posts. Use a future date to indicate when you plan to publish.
Media files must be uploaded via the /upload endpoint before being referenced in posts. Use the returned path value in the image array.
To get the correct settings schema for a specific platform, use the /integration-settings/:id endpoint before creating posts.

​
Next Steps

List Posts

Retrieve your scheduled and published posts

Upload Media

Upload images and videos for your posts

List Integrations

Get integration IDs for the posts array

Build docs developers (and LLMs) love

Get started for freeTalk to us