REST API

Postixly API Reference

Publish and manage social media posts across multiple platforms.

Base URL: https://api.postixly.com

Version: v1.0.0

Authentication

Include your API key in every request header. You can generate one in youraccount settings.

X-API-Key: your-api-key

JWT Bearer tokens are also accepted:Authorization: Bearer <token>

Posts

Create and manage social media posts

POST

/posts/

Create a post

Creates a new post and immediately enqueues it for publishing. Waits up to 30 s for the worker to finish so the response reflects the real status.

Request Body

contentstring

social_account_idsarrayrequiredConnection IDs to publish to

media_urlsarray

workspace_idstring (uuid)

platform_optionsPlatformOptions

Responses

201Default Response

400Default Response

401Default Response

403Default Response

404Default Response

409Default Response

500Default Response

Example

Shell · cURL

curl -X POST "https://api.postixly.com/posts/" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "Check out our latest update!",
  "social_account_ids": [],
  "media_urls": [],
  "workspace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

GET

/posts/

List posts

Returns a paginated list of posts for the authenticated account.

Query Parameters

workspace_idstringTeam account UUID

limitstringPage size (1–100, default 20)

offsetstringRecords to skip (default 0)

Responses

200Default Response

400Default Response

401Default Response

403Default Response

404Default Response

409Default Response

500Default Response

Example

Shell · cURL

curl -X GET "https://api.postixly.com/posts/" \
  -H "X-API-Key: <your-api-key>"

POST

/posts/schedule

Schedule a post

Creates a post and schedules it for future publishing.

Request Body

contentstring

scheduled_atstring (date-time)required

social_account_idsarrayrequiredConnection IDs to publish to

media_urlsarray

workspace_idstring (uuid)

platform_optionsPlatformOptions

Responses

201Default Response

400Default Response

401Default Response

403Default Response

404Default Response

409Default Response

500Default Response

Example

Shell · cURL

curl -X POST "https://api.postixly.com/posts/schedule" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "scheduled_at": "2026-06-01T10:00:00.000Z",
  "social_account_ids": []
}'

GET

/posts/{id}

Get a post

Returns a single post by ID.

Path Parameters

idstring (uuid)required

Responses

200Default Response

400Default Response

401Default Response

403Default Response

404Default Response

409Default Response

500Default Response

Example

Shell · cURL

curl -X GET "https://api.postixly.com/posts/{id}" \
  -H "X-API-Key: <your-api-key>"

PATCH

/posts/{id}

Update a scheduled post

Updates the content, media, or schedule time of a post that is in the `scheduled` status. Any other status returns 409.

Path Parameters

idstring (uuid)required

Request Body

contentstring

media_urlsarray

scheduled_atstring (date-time)

Responses

200Default Response

400Default Response

401Default Response

403Default Response

404Default Response

409Default Response

500Default Response

Example

Shell · cURL

curl -X PATCH "https://api.postixly.com/posts/{id}" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "Check out our latest update!",
  "media_urls": [],
  "scheduled_at": "2026-06-01T10:00:00.000Z"
}'

DELETE

/posts/{id}

Cancel a scheduled post

Cancels a post that is in the `scheduled` status and removes it from the queue. Returns the cancelled post.

Path Parameters

idstring (uuid)required

Responses

200Default Response

400Default Response

401Default Response

403Default Response

404Default Response

409Default Response

500Default Response

Example

Shell · cURL

curl -X DELETE "https://api.postixly.com/posts/{id}" \
  -H "X-API-Key: <your-api-key>"

POST

/posts/{id}/retry

Retry a failed post

Re-enqueues a post that is in the `failed` status for another publish attempt. Any other status returns 409.

Path Parameters

idstring (uuid)required

Responses

200Default Response

400Default Response

401Default Response

403Default Response

404Default Response

409Default Response

500Default Response

Example

Shell · cURL

curl -X POST "https://api.postixly.com/posts/{id}/retry" \
  -H "X-API-Key: <your-api-key>"

Webhooks

Manage event notification webhooks

GET

/webhooks/

List webhooks

Returns all webhooks for the authenticated account.

Query Parameters

workspace_idstringTeam account UUID

Responses

200Default Response

400Default Response

401Default Response

403Default Response

404Default Response

500Default Response

Example

Shell · cURL

curl -X GET "https://api.postixly.com/webhooks/" \
  -H "X-API-Key: <your-api-key>"

POST

/webhooks/

Create a webhook

Registers a new webhook endpoint. The signing secret is returned once and cannot be retrieved again.

Request Body

urlstring (uri)requiredHTTPS endpoint URL

eventsarray

workspace_idstring (uuid)

Responses

201Default Response

400Default Response

401Default Response

403Default Response

404Default Response

500Default Response

Example

Shell · cURL

curl -X POST "https://api.postixly.com/webhooks/" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://hooks.example.com/postixly",
  "events": [],
  "workspace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

PATCH

/webhooks/{id}

Update a webhook

Enables or disables an existing webhook.

Path Parameters

idstring (uuid)required

Request Body

activebooleanrequiredWhether the webhook is active

Responses

200Default Response

400Default Response

401Default Response

403Default Response

404Default Response

500Default Response

Example

Shell · cURL

curl -X PATCH "https://api.postixly.com/webhooks/{id}" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "active": true
}'

DELETE

/webhooks/{id}

Delete a webhook

Permanently removes a webhook.

Path Parameters

idstring (uuid)required

Responses

204Webhook deleted

400Default Response

401Default Response

403Default Response

404Default Response

500Default Response

Example

Shell · cURL

curl -X DELETE "https://api.postixly.com/webhooks/{id}" \
  -H "X-API-Key: <your-api-key>"

System

Health and diagnostics

GET

/livez

Liveness probe

Responses

200Default Response

Example

Shell · cURL

curl -X GET "https://api.postixly.com/livez" \
  -H "X-API-Key: <your-api-key>"

GET

/health

Health check (v1 alias)

Returns service health status.

Responses

200Default Response

503Default Response

Example

Shell · cURL

curl -X GET "https://api.postixly.com/health" \
  -H "X-API-Key: <your-api-key>"

GET

/api/media/proxy

Media proxy for TikTok PULL_FROM_URL domain verification

Query Parameters

urlstringrequired

Responses

200Default Response

Example

Shell · cURL

curl -X GET "https://api.postixly.com/api/media/proxy" \
  -H "X-API-Key: <your-api-key>"

Platform Options

Pass platform-specific settings under the platform_options field when creating or updating a post. Only include the key for the platforms you are targeting — omitted platforms use their defaults.

Structure

{
  "platform_options": {
    "tiktok":  { /* TikTok-specific fields */ },
    "youtube": { /* YouTube-specific fields */ }
  }
}

tiktokTikTok Options

TikTok-specific publish options (passed under `platform_options.tiktok`).

FieldTypeDefaultDescription

tiktokPrivacystringPUBLICWho can view the video. Available values depend on the creator account.

tiktokIsDraftbooleanfalseSave as draft instead of publishing immediately.

tiktokAllowCommentsbooleantrueAllow viewers to comment on the video.

tiktokAllowDuetbooleantrueAllow other creators to duet with this video.

tiktokAllowStitchbooleantrueAllow other creators to stitch with this video.

tiktokBrandContentbooleanfalseDisclose as paid partnership / branded content.

tiktokBrandOrganicbooleanfalseDisclose as promoting your own brand organically.

tiktokAutoAddMusicbooleanfalseLet TikTok automatically add background music.

tiktokIsAigcbooleanfalseMark the video as AI-generated content.

youtubeYouTube Options

YouTube-specific publish options (passed under `platform_options.youtube`).

FieldTypeDefaultDescription

youtubeTitlestring—Video title. Falls back to the first 100 characters of `content` if omitted.

youtubePrivacystringPUBLICVideo visibility.Allowed: PUBLICPRIVATEUNLISTED

youtubeTagsarray—Searchable tags for the video.

youtubeCategoryIdstring—YouTube category ID (e.g. "28" for Science & Technology, "22" for People & Blogs).

youtubeIsShortbooleanfalseInformational flag — YouTube auto-detects Shorts by aspect ratio and duration.

youtubeMadeForKidsbooleanfalseCOPPA compliance — mark the video as made for children.

youtubePlaylistIdstring—Playlist ID to add the video to after publishing.

youtubeThumbnailUrlstring—URL of a custom thumbnail image.