Create a post

Creates a draft, scheduled post, or immediate post. This endpoint requires a read-write API key. Provide exactly one creation mode: publishNow, scheduledFor, or isDraft.

Authorization

bearerAuth

AuthorizationBearer <token>

PostZen API key.

In: header

Header Parameters

x-request-id?string

Optional idempotency key. Repeating the same value returns the original post instead of creating a new one.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Provide exactly one creation mode: publishNow, scheduledFor, isDraft, or queuedFromProfile. platforms is required unless isDraft is true.

title?string

Internal post title. YouTube uses this as the fallback video title when settings.title is omitted.

content?string

Shared post text. Platform-specific validation still applies.

mediaItems?array<>

Duplicate URLs are removed before the post is created.

platforms?array<>

scheduledFor?string

ISO 8601 date for scheduled posts. Must be at least 60 seconds in the future.

publishNow?boolean

Publish synchronously where possible.

isDraft?boolean

Create a draft. platforms is optional for drafts.

queuedFromProfile?string

Profile id whose queue places the post. PostZen assigns the next free slot and returns it as scheduledFor. Do not call GET /v1/queue/next-slot and pass the result as scheduledFor: the slot is only claimed by the create call itself, so a fetched slot can be taken by another request before yours arrives, and the post would be scheduled outside the queue.

queueId?string

Specific queue on queuedFromProfile. Defaults to that profile's default queue. Requires queuedFromProfile.

timezone?string

Ignored in queue mode; queued posts take the queue's timezone.

tags?array<string>

Response Body

`application/json`

curl -X POST "https://example.com/v1/posts" \  -H "Content-Type: application/json" \  -d '{    "title": "Launch post",    "content": "We shipped the new release.",    "publishNow": true,    "platforms": [      {        "platform": "twitter",        "accountId": "1934567890123456789"      }    ]  }'

{  "existingPost": {    "_id": "jx58t2kqm4wr9v3n7c1zp6bs0dh5fg8y",    "title": "Launch post",    "content": "We shipped the new release.",    "status": "published",    "scheduledFor": null,    "timezone": "UTC",    "platforms": []  },  "message": "Post already exists for this request id"}

{  "post": {    "_id": "jx58t2kqm4wr9v3n7c1zp6bs0dh5fg8y",    "title": "Launch post",    "content": "We shipped the new release.",    "status": "published",    "scheduledFor": null,    "timezone": "UTC",    "platforms": [      {        "platform": "twitter",        "accountId": {          "_id": "j97kp4mw2xnv6r1t8c3zq5bs9fh0yg4d",          "platform": "twitter",          "username": "acme",          "displayName": "Acme",          "isActive": true        },        "status": "published",        "platformPostUrl": "https://x.com/acme/status/1934567890123456789"      }    ]  },  "message": "Post published successfully"}

{  "error": "JSON body is required"}

{  "error": "Unauthorized"}

{  "error": "The Free plan includes 2 connected accounts. Upgrade your plan to connect more.",  "code": "paymentRequired",  "reason": "freeTierExceeded",  "documentationUrl": "https://docs.postzen.dev/api-reference/connect/create-connect-url",  "dashboardUrl": "https://app.postzen.dev/settings?tab=billing",  "details": {    "planId": "free",    "includedAccounts": 2,    "freeTierAccountLimit": 2,    "currentAccountCount": 2,    "hasPaymentMethod": false  }}

{  "error": "API key requires read_write permission"}

{  "error": "Failed to create post"}

Authorization

Header Parameters

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

402application/json

403application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`