Posts

Create, list, and delete social media posts via the API.

Create post

POST /public/v1/posts

Create a new post as a draft, schedule it for later, or publish immediately.

Request

curl -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "schedule",
    "date": "2026-05-01T14:00:00Z",
    "posts": [
      {
        "channel": { "id": "channel-uuid" },
        "value": [
          {
            "content": "Check out our latest product launch!",
            "id": "unique-uuid",
            "image": []
          }
        ]
      }
    ]
  }' \
  https://api.postzee.app/public/v1/posts

Parameters

Parameter	Type	Required	Description
`type`	string	Yes	`"now"` (publish immediately), `"schedule"`, or `"draft"`
`date`	string	Schedule only	UTC datetime in ISO 8601 format (e.g., `"2026-05-01T14:00:00Z"`)
`posts`	array	Yes	Array of post objects (one per channel)
`posts[].channel.id`	string	Yes	Channel ID from the Channels endpoint
`posts[].value[].content`	string	Yes	Post text content
`posts[].value[].id`	string	Yes	Unique identifier (UUID) for this content block
`posts[].value[].image`	array	No	Array of media objects to attach
`posts[].settings`	object	No	Platform-specific settings (see below)
`tags`	array	No	Content tags (`[{ "value": "id", "label": "name" }]`)
`shortLink`	boolean	No	Enable URL shortening and click tracking

Platform-specific settings

Include these in posts[].settings for platform-specific features: TikTok:

{
  "tiktok": {
    "title": "Video title",
    "privacy_level": "PUBLIC_TO_EVERYONE",
    "duet": true,
    "stitch": true,
    "comment": true
  }
}

YouTube:

{
  "youtube": {
    "title": "Video title",
    "type": "public",
    "tags": [{ "value": "tag1", "label": "Tag 1" }]
  }
}

Instagram:

{
  "instagram": {
    "post_type": "post",
    "collaborators": [{ "label": "@username" }]
  }
}

LinkedIn:

{
  "linkedin": {
    "post_as_images_carousel": true
  }
}

Response

Returns an array with one entry per post that was created:

[
  {
    "postId": "post-uuid",
    "channel": { "id": "channel-uuid" }
  }
]

List posts

GET /public/v1/posts

Retrieve posts within a date range.

Request

curl -H "Authorization: YOUR_API_KEY" \
  "https://api.postzee.app/public/v1/posts?startDate=2026-04-01T00:00:00Z&endDate=2026-04-30T23:59:59Z"

Query parameters

Parameter	Type	Required	Description
`startDate`	string	Yes	Start date (ISO 8601)
`endDate`	string	Yes	End date (ISO 8601)
`customer`	string	No	Filter by customer ID

Response

{
  "posts": [
    {
      "id": "post-uuid",
      "content": "Post text content...",
      "state": "PUBLISHED",
      "releaseId": "17895695668004550",
      "releaseURL": "https://www.instagram.com/p/Cabc123/",
      "publishDate": "2026-04-15T14:00:00Z",
      "channel": {
        "id": "channel-uuid",
        "platform": "instagram",
        "name": "My Instagram",
        "picture": "https://..."
      }
    }
  ]
}

Get post status

GET /public/v1/posts/:id

Retrieve a single post’s publication status. Because publishing is asynchronous, use this to poll a post after creating it: once state is PUBLISHED, the response carries the platform post id (releaseId) and the public permalink (releaseURL).

Request

curl -H "Authorization: YOUR_API_KEY" \
  https://api.postzee.app/public/v1/posts/post-uuid-here

Parameters

Parameter	Type	Required	Description
`id`	string (path)	Yes	The post ID returned by Create post

Response

{
  "id": "post-uuid",
  "state": "PUBLISHED",
  "published": true,
  "releaseId": "17895695668004550",
  "releaseURL": "https://www.instagram.com/p/Cabc123/",
  "publishDate": "2026-04-15T14:00:00Z",
  "createdAt": "2026-04-15T13:58:00Z",
  "channel": {
    "id": "channel-uuid",
    "platform": "instagram",
    "name": "My Instagram"
  }
}

Field	Description
`state`	`QUEUE` (waiting to publish), `PUBLISHED`, `ERROR`, or `DRAFT`
`published`	`true` when `state` is `PUBLISHED`
`releaseId`	The native platform post id (e.g. the Instagram media id). `null` until published
`releaseURL`	The public permalink to the post. `null` until published

Publishing happens in the background, so right after Create post the state is QUEUE and releaseId is null. Poll this endpoint (or use a webhook) until state is PUBLISHED to read the releaseId.

Delete post

DELETE /public/v1/posts/:id

Delete a post by ID.

Request

curl -X DELETE \
  -H "Authorization: YOUR_API_KEY" \
  https://api.postzee.app/public/v1/posts/post-uuid-here

Parameters

Parameter	Type	Required	Description
`id`	string (path)	Yes	The post ID to delete

Response

Returns 200 OK on success.

Deleting a published post removes it from Postzee but does not remove it from the social media platform. To remove published content, you must delete it directly on the platform.

Find best time

GET /public/v1/find-slot/:id

Find the least congested time slot for posting.

Request

curl -H "Authorization: YOUR_API_KEY" \
  https://api.postzee.app/public/v1/find-slot/channel-uuid

Response

{
  "date": "2026-05-01T10:00:00Z"
}

Returns a suggested UTC datetime when your calendar is least busy.

Overview

Endpoints

Create post

Request

Parameters

Platform-specific settings

Response

List posts

Request

Query parameters

Response

Get post status

Request

Parameters

Response

Delete post

Request

Parameters

Response

Find best time

Request

Response

​Create post

​Request

​Parameters

​Platform-specific settings

​Response

​List posts

​Request

​Query parameters

​Response

​Get post status

​Request

​Parameters

​Response

​Delete post

​Request

​Parameters

​Response

​Find best time

​Request

​Response

Create post

Request

Parameters

Platform-specific settings

Response

List posts

Request

Query parameters

Response

Get post status

Request

Parameters

Response

Delete post

Request

Parameters

Response

Find best time

Request

Response