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

Metadata Constraints

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

Reserved metadata keys

Some metadata keys are read by platform adapters at publish time and are not treated as inert user data. Setting them changes what is published.

{
  "platformMetadata": {
    "YOUTUBE": { "youtubeTitle": "Full walkthrough — 12 min" },
    "PINTEREST": { "title": "5 quick tips" },
    "REDDIT": { "title": "We rebuilt our scheduler. AMA." }
  }
}

Platform Metadata

platformMetadata accepts per-platform metadata overrides. Keys are platform constants (e.g. "TIKTOK"); values are objects whose fields are merged into the post’s metadata for that platform. This is separate from platformOverrides, which overrides content/caption.

Validation constraints

Each platform’s metadata object must satisfy the following rules. Requests that violate these constraints return 400 VALIDATION_ERROR.

{
  "platformMetadata": {
    "TIKTOK": {
      "tiktokPrivacyLevel": "PUBLIC_TO_EVERYONE"
    }
  }
}

The following would be rejected:

{
  "platformMetadata": {
    "TIKTOK": {
      "nested": { "key": "value" }
    }
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "platformMetadata values must be string, number, boolean, null, or arrays of those types"
  }
}

Recognized keys

TIKTOK.tiktokPrivacyLevel (string, required for TikTok posts) — The TikTok privacy level for this post. TikTok’s Content Sharing Guidelines require an explicit, user-made privacy selection with nothing preselected, so this field has no default. Fetch GET /v1/accounts/:id/tiktok/creator-info first and pass one of the values in the account’s privacyLevelOptions.

• Omitting tiktokPrivacyLevel fails the TikTok publish with TIKTOK_PRIVACY_LEVEL_REQUIRED.
• Passing a value outside the account’s privacyLevelOptions fails with TIKTOK_PRIVACY_LEVEL_UNAVAILABLE.

Both are returned as platforms[].error.code on the post response, not a top-level 400 — TikTok fails independently of any other platforms in the same post. See TikTok publish errors.

Valid values:

Available values depend on what the connected TikTok account’s permissions allow. Accounts in unaudited or restricted states may only be allowed SELF_ONLY.

TIKTOK.tiktokAllowComment (boolean, default false) — Allow comments on this post. Has no effect if the creator has disabled comments on their own account (creatorInfo.commentDisabled).

TIKTOK.tiktokAllowDuet (boolean, default false) — Allow duets on this post. Has no effect if the creator has disabled duets on their own account (creatorInfo.duetDisabled).

TIKTOK.tiktokAllowStitch (boolean, default false) — Allow stitches on this post. Has no effect if the creator has disabled stitches on their own account (creatorInfo.stitchDisabled).

TIKTOK.tiktokCommercialContent (boolean, default false) — Enable commercial content disclosure for this post. When true, exactly one of tiktokBrandOrganic or tiktokBrandedContent must also be true, or the publish fails with TIKTOK_DISCLOSURE_INCOMPLETE.

TIKTOK.tiktokBrandOrganic (boolean, default false) — Discloses that the post promotes the creator’s own business (“Your brand”). Requires tiktokCommercialContent: true.

TIKTOK.tiktokBrandedContent (boolean, default false) — Discloses a paid partnership (“Branded content”). Requires tiktokCommercialContent: true. Cannot be combined with tiktokPrivacyLevel: "SELF_ONLY" — fails with TIKTOK_BRANDED_CONTENT_PRIVACY.

TIKTOK.tiktokAutoAddMusic (boolean, default false) — For photo posts, let TikTok automatically add a music track.

INSTAGRAM.instagramAudioId (string) — Attach a licensed audio track to an Instagram Reel. Use the id returned by GET /v1/instagram/audio/search. Only applies when the post contains a single video — ignored for images, carousels, and Stories. Requires a Facebook Login-connected Instagram account.

INSTAGRAM.instagramAudioVolume (number, 0.0–1.0, default 1.0) — Volume of the attached audio track relative to maximum. 0.0 is silent, 1.0 is full volume.

INSTAGRAM.instagramVideoVolume (number, 0.0–1.0, default 1.0) — Volume of the original video’s audio track. Set to 0.0 to mute the original video audio entirely (music-only), or blend with instagramAudioVolume for a mix.

{
  "content": "Summer vibes 🌊",
  "accountIds": ["acc_instagram_example"],
  "platformMetadata": {
    "INSTAGRAM": {
      "instagramAudioId": "1234567890",
      "instagramAudioVolume": 0.8,
      "instagramVideoVolume": 0.3
    }
  }
}

{
  "content": "New video!",
  "accountIds": ["acc_tiktok_example"],
  "platformMetadata": {
    "TIKTOK": {
      "tiktokPrivacyLevel": "FOLLOWER_OF_CREATOR"
    }
  }
}

First comment — platform support

firstComment is accepted on all post creation requests but is only posted on platforms that expose a comment API. On unsupported platforms it is silently skipped — the post publishes normally and no error is returned.

† Facebook first comment — pending Meta API approval. The pages_manage_engagement permission required for Facebook first comments is currently under review by Meta. Posts that include firstComment will publish normally — the comment is silently skipped on Facebook until the permission is approved and re-enabled.

Example Request

curl -X POST https://api.voxburst.io/v1/posts \
  -H "Authorization: Bearer vb_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,
      "publishWarning": null,
      "error": null,
      "attempts": []
    },
    {
      "postPlatformId": "pp_222",
      "platform": "linkedin",
      "accountId": "acc_456",
      "accountName": "My LinkedIn",
      "status": "pending",
      "platformPostId": null,
      "platformPostUrl": null,
      "publishedAt": null,
      "publishWarning": null,
      "error": null,
      "attempts": []
    }
  ]
}

The platforms array in the response 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. A non-null publishWarning indicates a non-fatal condition that occurred during publishing — see PostPlatform fields below.

Full Post Response Fields

Post media fields

Each entry in the media array describes one attached file.

PostPlatform fields

Each entry in the platforms array represents one publish destination. Fields marked (success only) are absent when status is not published.

publishWarning values

TikTok publish errors

These appear as platforms[].error.code for the TikTok entry when status is failed. They do not affect other platforms in the same post.

Account status on historical posts

Disconnecting a social account does not remove the platform rows on posts it has already published, so a published post can reference an account VoxBurst can no longer authenticate as. accountStatus reports that state:

Check accountStatus before calling Unpublish or a platform delete. Any value other than active means the platform-side operation cannot succeed and will return a failure reason — see Unpublish failure reasons.

Content Overrides

Use platformOverrides to customize content per platform constant. This is separate from accountIds (which targets accounts) and from the platforms array in responses (which tracks publish state):

platformOverrides schema

platformOverrides is a map keyed by platform constant (e.g. "TWITTER"). Each value supports:

{
  "content": "Announcing our new feature!",
  "accountIds": ["acc_123", "acc_456"],
  "platformOverrides": {
    "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."
    }
  }
}

threadPosts schema

Used with contentType: "THREAD" for X (Twitter) only. Threads (Meta) does not use this field — individual Threads posts do not support reply-chain threading through the API. Each item represents one post in the thread.

Constraints:

• Max 25 thread items per post
• Sequences must start at 1 and be contiguous (1, 2, 3 … — gaps are rejected)
• When contentType: "THREAD", each item counts as 1 post against your plan quota

{
  "content": "Thread opener — first tweet",
  "accountIds": ["acc_twitter_abc"],
  "contentType": "THREAD",
  "threadPosts": [
    { "sequence": 1, "content": "1/ This is the opening tweet of the thread." },
    { "sequence": 2, "content": "2/ The second tweet in the thread.", "mediaIds": ["media_abc123"] },
    { "sequence": 3, "content": "3/ Closing thoughts. Follow for more." }
  ]
}

Get Post

GET /v1/posts/:id

Retrieve a single post by ID.

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

List Posts

GET /v1/posts

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

Query Parameters

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

Response

{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6InBvc3RfYWJjMTIzIn0",
    "has_more": true,
    "limit": 50
  }
}

Update Post

PATCH /v1/posts/:id

Update a post. Posts in draft, scheduled, approved, failed, or partial status can be updated.

Required scopes: posts:write

Request Body

All fields are optional. Only include the fields you want to change.

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

Delete Post

DELETE /v1/posts/:id

Delete a post. Posts in publishing or published status cannot be deleted.

Required scopes: posts:write

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

Response (200):

{ "success": true }

Publish Now

POST /v1/posts/:id/publish

Immediately publish a draft or scheduled post.

Required scopes: posts:write

Query Parameters

Request Headers

curl -X POST "https://api.voxburst.io/v1/posts/post_abc123/publish?sync=true&timeout=60" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "X-Callback-Url: https://your-webhook-url.com/hooks/publish-done"

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

Backoff Schedule

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

Example Request

curl -X POST https://api.voxburst.io/v1/posts/post_abc123/retry \
  -H "Authorization: Bearer vb_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 platform on a partial or failed post. Eligible platform statuses are failed, publishing, and pending. 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

Path Parameters

Request Body

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

Example — Re-queue with corrected image

curl -X POST https://api.voxburst.io/v1/posts/post_abc123/platforms/pp_xyz789/fix \
  -H "Authorization: Bearer vb_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 vb_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

1. Your webhook receives a post.published event with status: "PARTIAL".
2. Inspect the platforms array on the post — each entry has its own status, error, and retryCount.
3. If the failure was transient (network error, rate limit), call POST /v1/posts/:id/retry to automatically re-queue all failed platforms with backoff.
4. 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.
5. 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

Post Status

All status values are returned as lowercase strings.

State transition table

The table below shows which statuses permit each operation. “Yes” means the operation is available; ”—” means it is blocked.

Terminal statuses (no further automatic transitions): published, cancelled, unpublished, archived.

User-triggered transitions:

• draft → scheduled: Set scheduledFor in a PATCH or at creation time
• draft / scheduled → publishing: Call POST /v1/posts/:id/publish
• draft / scheduled → cancelled: Call POST /v1/posts/:id/cancel
• published / partial → unpublished: Call POST /v1/posts/:id/unpublish
• failed / partial → publishing: Call POST /v1/posts/:id/retry or POST /v1/posts/:id/platforms/:id/fix

System-triggered transitions:

• scheduled → publishing: Scheduler cron fires when scheduledFor is reached
• approved → publishing: Approval workflow completes
• publishing → published: All platform workers complete successfully
• publishing → partial: At least one platform fails, at least one succeeds
• publishing → failed: All platforms fail

Scheduling Semantics

All scheduled times are specified using the scheduledFor field on POST /v1/posts or PATCH /v1/posts/:id.

Timestamp format

scheduledFor must be a valid ISO 8601 datetime string. Always use UTC to avoid ambiguity around daylight saving transitions:

2026-06-15T14:00:00Z        ✅  UTC (recommended)
2026-06-15T10:00:00-04:00   ✅  Offset included
2026-06-15T14:00:00          ❌  No timezone — rejected

Minimum lead time

The scheduled time must be in the future. The API allows a 60-second grace window to account for clock skew between your system and VoxBurst’s servers. Requests where scheduledFor is more than 60 seconds in the past return 400 VALIDATION_ERROR.

Exception — saveAsDraft: true: When saveAsDraft: true is set, the future-date validation is bypassed entirely. You may supply any scheduledFor value, including past timestamps. This is intended for import workflows where historical posts need to preserve their original date for calendar positioning. The post is saved as a draft regardless of the scheduledFor value — it is not automatically scheduled for publishing.

Maximum scheduling horizon

There is no maximum scheduling horizon. You can schedule posts years in advance.

Rescheduling

To reschedule a post, PATCH /v1/posts/:id with a new scheduledFor. The post must be in draft, scheduled, approved, failed, or partial status. Set clearSchedule: true to remove the scheduled time and revert the post to draft.

Queue mode

Set queue: true (instead of scheduledFor) to automatically assign the next available slot in your workspace’s posting queue. These are mutually exclusive — you cannot set both.

DST guidance

Use UTC timestamps for reliability. If you need to schedule at a user-local time, convert to UTC in your application before calling the API. VoxBurst stores and compares all times in UTC.

Validate Post

POST /v1/posts/validate

Validate content against platform rules without creating a post. Returns per-platform errors and warnings.

Request Body

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

Response

{
  "valid": true,
  "platforms": {
    "TWITTER": {
      "valid": true,
      "errors": [],
      "warnings": [
        { "code": "NO_HASHTAGS", "message": "Posts with hashtags typically get more reach on Twitter" }
      ]
    },
    "LINKEDIN": {
      "valid": true,
      "errors": [],
      "warnings": []
    }
  }
}

Bulk Generate Check

GET /v1/posts/bulk-generate-check

Check for scheduling conflicts before bulk-generating posts. Returns a warning and a count of already-scheduled posts in the requested date range.

Query Parameters

curl "https://api.voxburst.io/v1/posts/bulk-generate-check?accountId=acc_123&startDate=2026-04-01T00:00:00Z&endDate=2026-04-30T23:59:59Z" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response

{
  "warning": "duplicate_detected",
  "warningMessage": "A similar bulk generation was run recently for this account and platform. You may be creating duplicate posts.",
  "overlappingScheduledCount": 12
}

When no conflict is found, warning is null, warningMessage is omitted, and overlappingScheduledCount is 0:

{
  "warning": null,
  "overlappingScheduledCount": 0
}

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.

Query Parameters

curl "https://api.voxburst.io/v1/posts/preflight?platforms=TWITTER,INSTAGRAM" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response

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

Bulk Create Posts

POST /v1/posts/bulk

Create up to 50 posts in a single request. Each post in the posts array is processed independently. Add "dryRun": true to validate without creating any posts.

Required scopes: posts:write

Request Body

Idempotency: POST /v1/posts/bulk accepts the Idempotency-Key header. Provide a unique key per bulk request to prevent duplicate batch submissions on retries. On a replay, the entire original 207 response is returned.

curl -X POST https://api.voxburst.io/v1/posts/bulk \
  -H "Authorization: Bearer vb_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" }
    ]
  }'

Response (207)

{
  "dry_run": false,
  "total": 2,
  "created": 2,
  "failed": 0,
  "results": [
    { "index": 0, "status": "created", "postId": "post_abc1" },
    { "index": 1, "status": "created", "postId": "post_abc2" }
  ]
}

Dry runs return HTTP 200 instead of 207. Each results item has status: "valid" or status: "failed" with an errors array when invalid.

Bulk semantics

When a post in the batch fails, its results entry contains "status": "failed" and an errors array describing the validation or creation error. Successfully created posts are not affected.

Bulk Video Posts

POST /v1/posts/bulk-video

Create up to 20 posts in a single request, each tied to a pre-uploaded validated video. Use this after bulk video upload (see Bulk Upload in the Media docs) and validation.

Required scopes: posts:write

Request Body

curl -X POST https://api.voxburst.io/v1/posts/bulk-video \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "posts": [
      {
        "mediaId": "media_abc123",
        "accountIds": ["acc_123"],
        "scheduledFor": "2026-04-20T10:00:00Z",
        "content": "Watch our latest reel!"
      },
      {
        "mediaId": "media_def456",
        "accountIds": ["acc_123", "acc_456"],
        "scheduledFor": "2026-04-20T12:00:00Z",
        "content": "Behind the scenes!"
      }
    ]
  }'

Response (207)

{
  "created": [
    {
      "id": "post_xyz1",
      "content": "Watch our latest reel!",
      "status": "scheduled",
      "scheduledFor": "2026-04-20T10:00:00Z",
      "platforms": [ "..." ]
    }
  ],
  "warnings": []
}

The response uses HTTP 207 (Multi-Status). Each item in created is a full post object (same shape as POST /v1/posts). Check the warnings array for any videos that could not be posted (e.g. media not in READY state) — these are excluded from created.

Recurring Posts

Recurring rules allow a published or scheduled post to be automatically re-published on a repeating schedule defined by an iCal RRULE  string.

Plan limits

Create Recurrence Rule

POST /v1/posts/:id/recurrence

Attach a recurrence rule to a PUBLISHED or SCHEDULED post. Each re-run clones the post and publishes it fresh.

Required scopes: posts:write

Request Body

curl -X POST https://api.voxburst.io/v1/posts/post_abc123/recurrence \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "recurrenceRule": "RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR",
    "timezone": "America/New_York",
    "maxOccurrences": 24
  }'

Response (201)

Returns the full recurrence rule record including the computed nextRunAt.

Get Recurrence Rule

GET /v1/posts/:id/recurrence

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

Update Recurrence Rule

PATCH /v1/posts/:id/recurrence

Update or pause/resume an existing recurrence rule.

Required scopes: posts:write

Delete Recurrence Rule

DELETE /v1/posts/:id/recurrence

Soft-disables the recurrence rule. The source post and all previously created clone posts are preserved.

Required scopes: posts:write

Response: 204 No Content

Cancel Post

POST /v1/posts/:id/cancel

Cancel a scheduled post. Only posts in draft or scheduled status can be cancelled. Cancelled posts are not deleted and remain visible in the post list with status: "cancelled".

Required scopes: posts:write

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

Unpublish Post

POST /v1/posts/:id/unpublish

Attempts to delete the published post from each connected social platform, then marks the post as unpublished in VoxBurst. Only published or partial posts can be unpublished.

Required scopes: posts:write

Platforms that support post deletion will have the post removed. Platforms that do not support deletion are returned in unsupported_platforms — you must remove posts on those platforms manually.

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

Response

{
  "results": {
    "INSTAGRAM": { "success": true },
    "TWITTER": { "success": false, "reason": "platform_not_supported" }
  },
  "unsupported_platforms": ["TWITTER"],
  "note": "Posts on unsupported platforms must be deleted manually."
}

Unpublish failure reasons

results[platform].reason is a stable, machine-readable string. Branch on these values rather than on the human-readable text:

Get Post Replies

GET /v1/posts/:id/replies

Fetches replies for a published Threads post.

Required scopes: posts:read

Threads only. Returns { "data": [] } for posts not published on Threads. For posts published on Threads, replies are fetched using the connected Threads account’s access token.

Returns at most 25 replies per call.

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

Response

{
  "data": [
    {
      "id": "string",
      "text": "string",
      "username": "string",
      "timestamp": "2026-06-15T14:05:00Z",
      "permalink": "https://www.threads.net/@username/post/ABC123"
    }
  ]
}

Clone Post

POST /v1/posts/:id/clone

Create a copy of an existing post as a new draft. The clone inherits the original’s content, media, platform targets, and overrides, but is saved as draft with no scheduled time and no platform publish records.

Required scopes: posts:write

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

Response (201)

Returns the full post object of the newly created draft.

Duplicate Post

POST /v1/posts/:id/duplicate

Alias for Clone — creates a copy of a post as a new draft. Behaves identically to /clone.

Required scopes: posts:write

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

CSV Import

Import posts in bulk from a CSV file. The import is asynchronous — you upload the file, receive a jobId, then poll for completion.

Download Template

GET /v1/posts/import/template

Returns a CSV file with the correct column headers and example rows.

curl https://api.voxburst.io/v1/posts/import/template \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -o voxburst-import-template.csv

Upload CSV

POST /v1/posts/import

Required scopes: posts:write

Upload a CSV file to create posts in bulk. Send the file as multipart/form-data with the file in the file field. Add ?dry_run=true to validate without creating any posts.

# Dry run (validate only)
curl -X POST "https://api.voxburst.io/v1/posts/import?dry_run=true" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -F "file=@posts.csv;type=text/csv"
 
# Real import
curl -X POST https://api.voxburst.io/v1/posts/import \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -F "file=@posts.csv;type=text/csv"

Response (202)

{
  "jobId": "job_import_abc123",
  "status": "queued"
}

Check Import Status

GET /v1/posts/import/:jobId/status

Poll this endpoint every 2–5 seconds until status is complete or failed.

curl https://api.voxburst.io/v1/posts/import/job_import_abc123/status \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

{
  "jobId": "job_import_abc123",
  "status": "done",
  "totalRows": 44,
  "processedRows": 44,
  "successCount": 42,
  "failureCount": 2,
  "errors": [
    { "row": 12, "message": "Invalid scheduledFor date format" }
  ],
  "createdPostIds": ["post_abc1", "post_abc2"]
}

Post Events

List Post Events

GET /v1/posts/:id/events

List all lifecycle events for a post in chronological order.

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

Response

{
  "events": [
    {
      "id": "evt_001",
      "type": "post.created",
      "createdAt": "2026-04-01T10:00:00Z",
      "data": {}
    },
    {
      "id": "evt_002",
      "type": "post.published",
      "createdAt": "2026-04-01T14:00:00Z",
      "data": { "status": "published" }
    }
  ]
}

Get Latest Post Event

GET /v1/posts/:id/events/latest

Returns the most recent lifecycle event for a post.

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