Public API guide

Base URL

All paths in the API reference start with:

https://app.postozo.com/public/v1

Requests and answers are JSON (UTF-8), except file uploads, which are multipart form data. A JSON body can be up to 5 MB.

Authentication

Send your key in the Authorization header on every request. The Bearer prefix is optional.

Authorization: pz_live_YOUR_KEY
Authorization: Bearer pz_live_YOUR_KEY

Keep keys out of code you share and out of logs. If a key leaks, press Rotate Key in Settings, Developers: the old key stops working at once. Tokens for apps and the CLI are listed in Settings, Approved Apps, where you can revoke each 1. A workspace key also stops working when the workspace owner's account is suspended.

Your first post

1. Find the id of a channel:

curl "https://app.postozo.com/public/v1/integrations" \
  -H "Authorization: pz_live_YOUR_KEY"

[
  {
    "id": "de53f029-255d-4104-b090-974efcca2c86",
    "name": "acme",
    "identifier": "demo",
    "picture": null,
    "disabled": false,
    "refreshNeeded": false,
    "inBetweenSteps": false,
    "profile": "acme"
  }
]

2. Check the network's rules for that channel (limit, media, required settings):

curl "https://app.postozo.com/public/v1/integration-settings/de53f029-255d-4104-b090-974efcca2c86" \
  -H "Authorization: pz_live_YOUR_KEY"

3. Schedule a post with a first comment 5 minutes later:

curl -X POST "https://app.postozo.com/public/v1/posts" \
  -H "Authorization: pz_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "schedule",
  "date": "2026-10-01T09:30:00+05:30",
  "posts": [
    {
      "integration": {
        "id": "de53f029-255d-4104-b090-974efcca2c86"
      },
      "value": [
        {
          "content": "Our autumn menu is here."
        },
        {
          "content": "Book a table: https://example.com",
          "delay": 5
        }
      ],
      "settings": {}
    }
  ]
}'

The answer has 1 row per channel with the postId, the group id of the whole post and a previewUrl you can share. Use "type": "now" to publish right away, "draft" to save it only, or "review" to send it to your client first. The full body is in the POST /posts reference.

4. Check the result later with GET /posts/{id}. Each channel has a state: queued, publishing, published with a releaseUrl, or error with a message and a fix. Or add a webhook and get told.

Errors

Every error is JSON with the message twice: error and msg (the Postiz name). Some errors add more fields:

• errors: a list of problems per channel when a post breaks a network rule, each { channelId, channelName, message }.
• fix: what to do. Plan limits, a workspace with no plan or a failed payment, paused access, ids that are not valid, unknown paths, conflicts and server errors all have 1.
• code: a stable name for some errors, for example no_subscription, payment_failed, idempotency_key_reused, email_not_verified or member_paused.

{
  "error": "Please fix these before saving.",
  "msg": "Please fix these before saving.",
  "errors": [
    {
      "channelId": "de53f029-255d-4104-b090-974efcca2c86",
      "channelName": "acme (Demo)",
      "message": "acme (Demo): the post is too long, 1200 of 1000 characters."
    }
  ]
}

Errors of a post that failed on the network are not HTTP errors: the post is saved and its channel gets state: "error" with error: { message, fix }, for example "The post is longer than this network allows." with "Shorten the text for this channel, then retry."

Every common error, exactly as the server sends it:

Rate limits

Each window starts with the first request and lasts the full hour (or minute). Over the limit, the answer is 429 with {"error": "Too many requests. Try again in 42 minutes.", "msg": "..."} and a Retry-After header with the seconds until the window starts again, for example Retry-After: 2520. The limits are counted by the server in memory, so they start again after a server restart. 1 request to POST /posts can hold many channels, so put all the channels of 1 post in 1 request.

Paging

• GET /posts has no pages. It returns every post between startDate and endDate (default: 30 days back to 30 days ahead). Ask for shorter ranges to get fewer rows.
• GET /media returns 40 files a page. Send page=2, page=3 and so on. A page with fewer than 40 files is the last.
• GET /notifications returns 50 a page with the same page parameter, and echoes the page number.
• GET /integrations, GET /groups and GET /networks return everything at once.

Dates and time zones

• Send dates as ISO 8601 with a time zone: 2026-10-01T09:30:00+05:30 or 2026-10-01T04:00:00Z. Without a zone, the server's own zone is used, so always add 1.
• Answers are always UTC with milliseconds, for example 2026-10-01T04:00:00.000Z.
• A schedule or review post cannot be more than 1 minute in the past. Drafts can have any date. now ignores the date.
• The free slot endpoints (GET /find-slot and the MCP tool find_free_slot) read each channel's posting times (set in the app) as local times of day. Send tzOffsetMinutes, the minutes to add to UTC to get your local time (330 for India, -300 for New York in winter). Without it, the time zone in the profile of the person the key belongs to is used (the owner's for the workspace key), with daylight saving time; UTC when none is set. The answer is UTC: 9:00 in India comes back as 03:30:00.000Z.
• A date that does not parse gives 400 "The date is not valid. Use ISO 8601, for example 2026-10-01T09:30:00Z."

Sending twice: the Idempotency-Key header

Networks time out and scripts retry. To make a retry safe, send an Idempotency-Key header on POST /posts with a value that is new for each post, for example a UUID:

curl -X POST "https://app.postozo.com/public/v1/posts" \
  -H "Authorization: pz_live_YOUR_KEY" \
  -H "Idempotency-Key: 3f1c9a52-7d4e-4b8a-9c21-6e0f5d2b8a47" \
  -H "Content-Type: application/json" \
  -d '{"type": "draft", "posts": [{"integration": {"id": "de53f029-255d-4104-b090-974efcca2c86"}, "value": [{"content": "Only once"}], "settings": {}}]}'

• The same key from the same workspace within 24 hours, with the same body, returns the first answer (the same status and body) with the header Idempotent-Replayed: true. No 2nd post is made. The order of the keys in the JSON does not matter.
• The same key with a different body is refused: 409 "This Idempotency-Key was already used with a different request body." Use a new key for a new post.
• If the 2nd request comes while the 1st is still running, it gets 409 "A request with this Idempotency-Key is still running." Wait a few seconds and send it again to get the answer.
• Only answers that worked are kept. If the first request failed (for example 400 because the text is too long), fix the body and send it with the same key.
• Keys are up to 255 characters. They are forgotten after 24 hours. Each workspace has its own keys. Replays count toward the rate limit.
• Without the header, 2 identical requests make 2 posts. Then, after a timeout, call GET /posts for that time range and look for your text before you send it again.

The no double post rule

Publishing is different. Postozo writes down each attempt before it calls a network. If the network does not answer, the worker searches the network for the post. If it finds it, the post is marked published. If it cannot tell, the channel becomes unconfirmed (Postiz state ERROR), you get a notification and a post.unconfirmed webhook, and nothing is sent again until a person decides. Then either link the live post with PUT /posts/{id}/release-id, or retry with POST /posts/{id}/retry. GET /posts/{id}/missing asks the network for you.

Postiz compatibility

The API follows the Postiz public API: the same /public/v1 paths, the same Authorization: <key> header, the same POST /posts body and the same answer fields. To move a Postiz script or an n8n, Make or Zapier flow, change the base URL to https://app.postozo.com/public/v1 and use your Postozo key.

• Also in Postozo: GET /posts/{id}, POST /posts/{id}/retry, PUT /posts/{id}/date, GET /find-slot without a channel, GET /networks and GET /rules/{identifier}, the review post type and a simpler post body.
• Answers keep the Postiz fields and add a few, for example status and error with a fix in GET /posts.
• Not in Postozo: the Postiz video generation, clipping, user and debug endpoints.
• Delete answers {"error": false, "success": true}. The Postiz type update is read as schedule.

Next: the API reference with every endpoint, or webhooks to hear about results.