Publish

POST /api/v1/publish is the immediate-publish endpoint. It dispatches a payload to every platform in the platforms array in parallel, using the credentials the user has connected in their Post-EZ account. It is the same code path the in-app composer uses, so anything that ships from the UI will ship from this endpoint too.

Required scope: publish. Rate limit: 60 requests per minute per key.

Request

curl -X POST https://postez.app/api/v1/publish \
  -H "Authorization: Bearer pz_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": ["instagram", "x", "linkedin"],
    "content": "Shipping the public API today. /docs is live.",
    "title": "Public API",
    "media_urls": ["https://cdn.example.com/launch.png"]
  }'

Body fields

• platforms (string[], required) — one or more of instagram, tiktok, youtube, x, linkedin, facebook, threads, pinterest, bluesky, mastodon, patreon, beehiiv, ghost, twitch, youtube_live, kick, kajabi, discord. Unknown values are silently dropped.
• content (string, required) — the caption. Trimmed before dispatch. Per-platform character limits are enforced by the connector, not the API gateway — over-limit content fails per-platform, not for the whole call.
• title (string, optional) — used for surfaces that need a separate title field (Beehiiv, Ghost, YouTube). Ignored elsewhere.
• media_urls (string[], optional) — publicly-reachable URLs to attach. We download them server-side and re-upload to the destination platform. Signed URLs work as long as they are valid for ~60 seconds after the request.

Response

A 200 OK is returned for any call where at least one platform succeeded. Per-platform results are surfaced in results. You should always branch on the per-platform ok field, not just the top-level status code.

{
  "ok": true,
  "results": {
    "instagram": { "ok": true, "postId": "1234567890" },
    "x": { "ok": true, "postId": "1789...432" },
    "linkedin": { "ok": false, "error": "credential_revoked" }
  }
}

Per-platform notes

• Instagram, TikTok, YouTube — require at least one media URL; text-only posts are rejected by the platform.
• X — silently truncates content to 280 chars (or 25,000 if the account has X Premium).
• Beehiiv, Ghost — require title. Text becomes the newsletter body, rendered as HTML.
• Discord — uses the BYOK webhook URL; media_urls are attached as embeds.

Rate limits and errors

Exceeding 60 req/min returns 429 Too Many Requests with a Retry-After header in seconds. Validation errors return 400 with codes invalid_json, missing_content, or missing_platforms.