API Overview

For N8N, check out this video:

Official Postiz Node.js SDK

Authentication

There are two ways to authenticate with the Postiz API:

Your API key lives in Postiz under Settings → Developers → Public API. Click the reveal icon to show it, then copy. You can rotate it from the same place, rotating immediately invalidates the old key, so update anything using it (scripts, n8n, MCP clients, the CLI) at the same time.

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

Where Postiz runs	Base URL
Postiz Cloud	`https://api.postiz.com`
Self-hosted	your `NEXT_PUBLIC_BACKEND_URL`
Self-hosted, official Docker image	`http://localhost:4007/api` (the compose file maps host `4007` to container `5000`)
Self-hosted, running from source	`http://localhost:3000` (frontend is on `4200`)

Public API paths are appended to the base URL, so a cloud request goes to https://api.postiz.com/public/v1/... and a self-hosted one to {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 does not 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

Status	Meaning
`400 Bad Request`	The request body or path parameter is malformed (wrong shape, unknown enum, missing required field).
`401 Unauthorized`	`Authorization` header is missing or the API key is unrecognised.
`403 Forbidden`	The API key is valid but doesn't own the resource (e.g. you tried to delete a post in another organisation).
`404 Not Found`	The endpoint doesn't exist, or the path parameter (integration ID, post ID) was correct format but no row matched.
`413 Payload Too Large`	Your request body exceeded 50 MB on `/posts`, usually because images were base64-inlined instead of pre-uploaded. See Uploads troubleshooting.
`429 Too Many Requests`	You exceeded `API_LIMIT` per hour on the create-post endpoint.
`5xx`	Server 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	`__type`	Key settings
X (Twitter)	`x`	`who_can_reply_post`, `community`
LinkedIn	`linkedin`	`post_as_images_carousel`
LinkedIn Page	`linkedin-page`	`post_as_images_carousel`
Facebook	`facebook`	`url` (optional)
Instagram (FB-linked)	`instagram`	`post_type`, `collaborators`
Instagram Standalone	`instagram-standalone`	`post_type`, `collaborators`
Warpcast (Farcaster)	`warpcast`	`subreddit[]` (channels)

Platforms without custom settings (7)

These platforms only require { "__type": "platform-name" }:

Platform	`__type`
Threads	`threads`
Mastodon	`mastodon`
Bluesky	`bluesky`
Telegram	`telegram`
Nostr	`nostr`
VK	`vk`
Kick	`kick`

{
  "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"
      }
    }
  ]
}

API Overview

SDKs & Integrations

Node.js SDK

n8n Node