Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.postiz.com/llms.txt

Use this file to discover all available pages before exploring further.

For N8N, check out this video:https://www.youtube.com/watch?v=c50u3K3xsCI

​
SDKs & Integrations

NodeJS SDK

Official Postiz NodeJS SDK

n8n Node

Custom n8n node for Postiz

​
Authentication

There are two ways to authenticate with the Postiz API:

​
API Key

Get your API key from Settings > Developers > Public API. Include it in the Authorization header: 
curl -H "Authorization: your-api-key" https://api.postiz.com/public/v1/integrations

​
OAuth2 Token

If you’re building an app for other Postiz users, use OAuth2 Authentication to get tokens that act on behalf of users. OAuth tokens start with pos_ and are used the same way: 
curl -H "Authorization: pos_your-oauth-token" https://api.postiz.com/public/v1/integrations

​
Base URL

EnvironmentBase URL
Postiz Cloudhttps://api.postiz.com/public/v1
Self-hostedhttps://{NEXT_PUBLIC_BACKEND_URL}/public/v1

​
Rate Limits

90 requests per hour (100 for the cloud) limit applies to only the create post endpoint.This doesn’t mean you can only post 90 times per hour—each API call counts as one request. Schedule multiple posts in a single request to maximize throughput.
The rate limit is a single global value for the whole instance — it doesn’t tier by subscription plan. Plans tier on channel and post-per-month quotas instead. Self-hosters can adjust the per-hour limit with the API_LIMIT env var (see Configuration Reference).

​
Errors

StatusMeaning
400 Bad RequestThe request body or path parameter is malformed (wrong shape, unknown enum, missing required field).
401 UnauthorizedAuthorization header is missing or the API key is unrecognised.
403 ForbiddenThe API key is valid but doesn’t own the resource (e.g. you tried to delete a post in another organisation).
404 Not FoundThe endpoint doesn’t exist, or the path parameter (integration ID, post ID) was correct format but no row matched.
413 Payload Too LargeYour request body exceeded 50 MB on /posts — usually because images were base64-inlined instead of pre-uploaded. See Uploads troubleshooting.
429 Too Many RequestsYou exceeded API_LIMIT per hour on the create-post endpoint.
5xxServer error — retry with exponential backoff.
For DELETE endpoints, 404 always means “already deleted” and is safe to ignore. A 500 can mean the same thing today because of a known issue where a missing post ID surfaces as 500 instead of 404 — but only if the error matches that specific signature. Treat other 500 responses as real server errors: log them, retry with exponential backoff, and don’t silently suppress them.

​
Terminology

The Postiz UI uses the term channel, while the API uses integration. They refer to the same thing—a connected social media account.

​
Generate Output

The easiest way to generate your post payloads is by using this wizard. It’s the same wizard to schedule posts in the Postiz app, however instead of scheduling posts, it generates the JSON payload for you to use in your API requests.
  • For cloud, make sure you are logged in.
  • For local, make sure your Postiz server is running and your are logged in.
Open in full screen

​
Supported Platforms (32 total)

When creating posts, each social media platform has its own settings schema. The settings object must include a __type field matching the provider.

​
Platforms with custom settings (25)

Platform__typeKey settings
X (Twitter)xwho_can_reply_post, community
LinkedInlinkedinpost_as_images_carousel
LinkedIn Pagelinkedin-pagepost_as_images_carousel
Facebookfacebookurl (optional)
Instagram (FB-linked)instagrampost_type, collaborators
Instagram Standaloneinstagram-standalonepost_type, collaborators
Warpcast (Farcaster)warpcastsubreddit[] (channels)

​
Platforms without custom settings (7)

These platforms only require { "__type": "platform-name" }:
Platform__type
Threadsthreads
Mastodonmastodon
Blueskybluesky
Telegramtelegram
Nostrnostr
VKvk
Kickkick

View Provider Settings Reference

See detailed settings schemas with examples for each platform

​
Quick Examples

​
Schedule a post to X (Twitter)

{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": { "id": "your-integration-id" },
      "value": [
        {
          "content": "Hello from the Postiz API! 🚀",
          "image": []
        }
      ],
      "settings": {
        "__type": "x",
        "who_can_reply_post": "everyone"
      }
    }
  ]
}

​
Post immediately to LinkedIn

{
  "type": "now",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": { "id": "your-linkedin-id" },
      "value": [
        {
          "content": "Exciting announcement! 🎉",
          "image": []
        }
      ],
      "settings": {
        "__type": "linkedin"
      }
    }
  ]
}

​
Upload an image and post to Instagram

# Step 1: Upload the image
curl -X POST "https://api.postiz.com/public/v1/upload" \
  -H "Authorization: your-api-key" \
  -F "file=@photo.jpg"

# Response: { "id": "img-123", "path": "https://uploads.postiz.com/photo.jpg", ... }

# Step 2: Create the post with the uploaded image
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-14T10:00:00.000Z",
    "shortLink": false,
    "tags": [],
    "posts": [{
      "integration": { "id": "your-instagram-id" },
      "value": [{
        "content": "Beautiful sunset 🌅 #photography",
        "image": [{ "id": "img-123", "path": "https://uploads.postiz.com/photo.jpg" }]
      }],
      "settings": {
        "__type": "instagram",
        "post_type": "post"
      }
    }]
  }'

​
Publish a Medium article

{
  "type": "now",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": { "id": "your-medium-id" },
      "value": [
        {
          "content": "# Introduction\n\nThis is my article in markdown...",
          "image": []
        }
      ],
      "settings": {
        "__type": "medium",
        "title": "My Amazing Article",
        "subtitle": "A deep dive into something interesting",
        "tags": [
          { "value": "programming", "label": "Programming" }
        ]
      }
    }
  ]
}

​
Create a Google My Business offer

{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": { "id": "your-gmb-id" },
      "value": [
        {
          "content": "🎉 Holiday Sale! 20% off everything!",
          "image": []
        }
      ],
      "settings": {
        "__type": "gmb",
        "topicType": "OFFER",
        "callToActionType": "GET_OFFER",
        "callToActionUrl": "https://example.com/sale",
        "offerCouponCode": "HOLIDAY20"
      }
    }
  ]
}