Posts

Create, schedule, update, and publish social media posts across multiple platforms simultaneously.

Base URL


https://api.voxburst.io/v1/posts

Create Post

POST /v1/posts

Creates a new post. Posts can be created as drafts, scheduled for a future time, or published immediately.

Required scopes: posts:write

Request Body

Field	Type	Required	Description
`content`	string	Yes	Post content. Used as the default for all platforms unless overridden.
`accountIds`	string[]	Yes	IDs of connected accounts to post from. The platform is inferred from each account.
`scheduledFor`	string	No	ISO 8601 datetime for scheduled publishing
`contentType`	string	No	Content type hint: `TEXT`, `IMAGE`, `VIDEO`, `CAROUSEL`, `STORY`, `REEL`
`saveAsDraft`	boolean	No	If `true`, saves as draft regardless of `scheduledFor`
`overrides`	object	No	Per-platform content overrides
`mediaIds`	string[]	No	IDs of previously uploaded media files
`tags`	string[]	No	Internal tags for organization (not posted to platforms)
`personaId`	string	No	ID of a persona profile to associate with this post
`threadPosts`	object[]	No	Additional thread items (X/Threads only)
`metadata`	object	No	Arbitrary key-value metadata. See Metadata Constraints.

Metadata Constraints

The metadata field accepts an arbitrary key-value object with the following limits. Requests violating these limits receive a 422 error.

Rule	Limit
Key length	Max 100 characters
String value length	Max 1,000 characters
Array value item count	Max 100 items
Array value item length	Max 200 characters each

Example Request


curl -X POST https://api.voxburst.io/v1/posts \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from VoxBurst!",
    "accountIds": ["acc_123", "acc_456"],
    "scheduledFor": "2026-04-20T14:00:00Z"
  }'

Response


{
  "id": "post_abc123",
  "content": "Hello from VoxBurst! 🚀",
  "status": "SCHEDULED",
  "scheduledFor": "2026-03-01T14:00:00Z",
  "createdAt": "2026-02-20T10:00:00Z",
  "updatedAt": "2026-02-20T10:00:00Z",
  "platforms": [
    {
      "postPlatformId": "pp_111",
      "platform": "twitter",
      "accountId": "acc_123",
      "accountName": "My Twitter",
      "status": "pending",
      "platformPostId": null,
      "platformPostUrl": null,
      "publishedAt": null,
      "error": null,
      "attempts": []
    },
    {
      "postPlatformId": "pp_222",
      "platform": "linkedin",
      "accountId": "acc_456",
      "accountName": "My LinkedIn",
      "status": "pending",
      "platformPostId": null,
      "platformPostUrl": null,
      "publishedAt": null,
      "error": null,
      "attempts": []
    }
  ]
}

The platforms array tracks per-platform publish state. After publishing, each entry’s status will be published (with a platformPostUrl) or failed (with an error message). The postPlatformId is used with the Fix Platform endpoint to resubmit a specific failed platform.

Platform Overrides

Use overrides to customize content per platform:


{
  "content": "Announcing our new feature!",
  "platforms": ["TWITTER", "LINKEDIN"],
  "accountIds": ["acc_123", "acc_456"],
  "overrides": {
    "TWITTER": {
      "content": "New feature alert! 🎉 #voxburst"
    },
    "LINKEDIN": {
      "content": "We're excited to announce our latest feature that helps teams schedule social media content more efficiently. Read more on our blog."
    }
  }
}

Use platform overrides to optimize content for each platform’s audience and character limits. Twitter gets hashtags, LinkedIn gets professional tone.

Get Post

GET /v1/posts/:id

Retrieve a single post by ID.

Required scopes: posts:read


curl https://api.voxburst.io/v1/posts/post_abc123 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

List Posts

GET /v1/posts

List all posts with optional filtering. Uses cursor-based pagination.

Required scopes: posts:read

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: `DRAFT`, `SCHEDULED`, `PUBLISHED`, `FAILED`, `PARTIAL`, `CANCELLED`, `UNPUBLISHED`
`platform`	string	Filter by platform
`from`	string	Start date (ISO 8601)
`to`	string	End date (ISO 8601)
`limit`	number	Results per page (default: 20, max: 100)
`cursor`	string	Pagination cursor from previous response


curl "https://api.voxburst.io/v1/posts?status=SCHEDULED&limit=50" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Response


{
  "posts": [...],
  "pagination": {
    "cursor": "eyJpZCI6InBvc3RfYWJjMTIzIn0",
    "hasMore": true
  }
}

Update Post

PATCH /v1/posts/:id

Update a post. Only DRAFT and SCHEDULED posts can be updated.

Required scopes: posts:write


curl -X PATCH https://api.voxburst.io/v1/posts/post_abc123 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated content!",
    "scheduledFor": "2026-03-02T14:00:00Z"
  }'

Published posts cannot be modified. To change published content, delete the original post and create a new one.

Delete Post

DELETE /v1/posts/:id

Delete a post. Published posts cannot be deleted through the API.

Required scopes: posts:write


curl -X DELETE https://api.voxburst.io/v1/posts/post_abc123 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Deleting a post removes it from VoxBurst but does not delete it from social platforms if already published. You must delete published posts manually on each platform.

Publish Now

POST /v1/posts/:id/publish

Immediately publish a draft or scheduled post.

Required scopes: posts:write


curl -X POST https://api.voxburst.io/v1/posts/post_abc123/publish \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Retry Failed Post

POST /v1/posts/:id/retry

Retries all failed platform targets on a FAILED or PARTIAL post. Successfully published platforms are never re-posted — only platforms with a FAILED status are re-queued. Retries are subject to exponential backoff and a per-platform maximum of 3 attempts.

Required scopes: posts:write

This endpoint is idempotent when called with an Idempotency-Key header. Provide a unique key per retry attempt to avoid duplicate submissions.

Backoff Schedule

Each platform tracks its own retryCount. The delay before the next attempt doubles with each failure:

Retry attempt	Delay
1st retry	2 minutes
2nd retry	4 minutes
3rd retry	8 minutes
After 3rd	Platform exhausted — use Fix Platform to reset

Example Request


curl -X POST https://api.voxburst.io/v1/posts/post_abc123/retry \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
  -H "Idempotency-Key: retry-post_abc123-attempt-1"

Response


{
  "id": "post_abc123",
  "status": "publishing",
  "retriedPlatforms": [
    {
      "platform": "instagram",
      "accountId": "acc_789",
      "retryCount": 1,
      "nextRetryAt": "2026-04-02T14:02:00Z"
    }
  ],
  "skippedPlatforms": [
    {
      "platform": "facebook",
      "accountId": "acc_456",
      "retryCount": 3,
      "reason": "max_retries_exceeded"
    }
  ]
}

skippedPlatforms lists any failed platforms that have already hit the 3-retry limit. Use the Fix Platform endpoint to reset these manually.

Fix Platform

POST /v1/posts/:id/platforms/:platformId/fix

Fixes and re-queues a single failed platform on a PARTIAL or FAILED post. Unlike /retry, this endpoint resets the platform’s retry counter to zero and optionally lets you supply a replacement image URL or content — useful when the original failure was caused by an invalid or rejected image.

Required scopes: posts:write

Use this endpoint when a platform has exhausted its automatic retries (retryCount = 3) or when you need to correct the media or caption before resubmitting.

Path Parameters

Parameter	Description
`id`	Post ID
`platformId`	The `id` of the specific `PostPlatform` entry to fix. Found in the post’s `platforms` array.

Request Body

All fields are optional. Omitting the body re-queues the platform with its original content.

Field	Type	Required	Description
`mediaUrl`	string	No	Replacement image URL (`https://` only). Use when the original image was rejected by the platform (e.g., wrong aspect ratio, size exceeded).
`content`	string	No	Replacement caption or post text for this platform only.

Example — Re-queue with corrected image


curl -X POST https://api.voxburst.io/v1/posts/post_abc123/platforms/pp_xyz789/fix \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaUrl": "https://cdn.example.com/corrected-image-1080x1080.jpg"
  }'

Example — Re-queue with no changes


curl -X POST https://api.voxburst.io/v1/posts/post_abc123/platforms/pp_xyz789/fix \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Response


{
  "success": true,
  "platformId": "pp_xyz789",
  "status": "publishing"
}

After a successful response, the parent post status returns to PUBLISHING. The platform is re-queued immediately without backoff delay (retryCount is reset to 0).

Handling Partial Failures

A post reaches PARTIAL status when at least one platform publishes successfully and at least one fails. Platforms that succeeded are not affected by retry or fix operations — only FAILED platforms are re-queued.

Typical partial failure workflow

Your webhook receives a post.published event with status: "PARTIAL".
Inspect the platforms array on the post — each entry has its own status, error, and retryCount.
If the failure was transient (network error, rate limit), call POST /v1/posts/:id/retry to automatically re-queue all failed platforms with backoff.
If the failure was caused by invalid content (e.g., Instagram rejected the image), call POST /v1/posts/:id/platforms/:platformId/fix with a corrected mediaUrl or content.
If a platform has retryCount: 3, automatic retries are exhausted — /retry will skip it. You must use /fix to reset the counter and resubmit.

Platform status values

Status	Description
`PENDING`	Waiting to be sent
`PUBLISHING`	Currently being submitted to the platform
`PUBLISHED`	Successfully posted
`FAILED`	Publish attempt failed — eligible for retry or fix
`SKIPPED`	Excluded from this run

If all platforms fail, the post status is FAILED (not PARTIAL). Both statuses are eligible for /retry and /fix.

Post Status

Status	Description
`DRAFT`	Created but not scheduled or published
`SCHEDULED`	Queued for future publishing
`PUBLISHING`	Currently being sent to platforms
`PUBLISHED`	Successfully published to all platforms
`FAILED`	Publishing failed on all platforms
`PARTIAL`	Published to some platforms; at least one failed — use `/retry` or `/fix` to remediate
`CANCELLED`	Post was cancelled before publishing
`UNPUBLISHED`	Post was unpublished after a successful publish

Validate Post

POST /v1/posts/validate

Validate a post payload without creating it. Returns validation errors and platform-specific warnings.

Required scopes: posts:write


curl -X POST https://api.voxburst.io/v1/posts/validate \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Test post content",
    "accountIds": ["acc_123"]
  }'

Pre-flight Check

GET /v1/posts/preflight

Run distribution intelligence pre-flight checks for a set of accounts before creating a post. Returns risk tier and scheduling guidance per platform.

Required scopes: posts:read

Query Parameters

Parameter	Type	Description
`accountIds`	string	Comma-separated account IDs to check


curl "https://api.voxburst.io/v1/posts/preflight?accountIds=acc_123,acc_456" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Response


{
  "results": [
    {
      "accountId": "acc_123",
      "platform": "INSTAGRAM",
      "tier": "GREEN",
      "tierLabel": "Optimal",
      "guidance": [],
      "isVerified": true
    }
  ]
}

Bulk Create Posts

POST /v1/posts/bulk

Create multiple posts in a single request. Each post in the array is processed independently.

Required scopes: posts:write


curl -X POST https://api.voxburst.io/v1/posts/bulk \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "posts": [
      { "content": "Post one", "accountIds": ["acc_123"] },
      { "content": "Post two", "accountIds": ["acc_456"], "scheduledFor": "2026-04-20T10:00:00Z" }
    ]
  }'