Skip to Content
Getting Started

Getting Started

Build social media integrations in minutes. This guide walks you through your first API calls.

Quick Start

Get Your API Key

Sign in to your VoxBurst dashboard  and create an API key with the scopes you need:

ScopeDescription
posts:readRead posts
posts:writeCreate, update, delete, publish posts
accounts:readList connected social accounts
accounts:writeConnect and disconnect accounts
media:readView uploaded media
media:writeUpload media files
webhooks:readView webhook configurations
webhooks:writeCreate and manage webhooks
personas:writeCreate, update, and manage personas
billing:writePreview plan changes, change plans, manage add-ons, and purchase credits
hashtag-sets:writeCreate, update, and delete hashtag sets

Make Your First Request

curl https://api.voxburst.io/v1/accounts \
  -H "Authorization: Bearer vb_live_your_api_key_here"

Or use the CLI for quick one-off commands:

npm install -g @voxburst/cli
voxburst accounts list

Environment Setup

Set these environment variables in your project:

VOXBURST_API_KEY=vb_live_xxxxxxxxxxxxx
VOXBURST_API_URL=https://api.voxburst.io/v1  # optional — defaults to production; matches CLI env var

First API Call Examples

List Connected Accounts

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

Create a Draft Post

curl -X POST https://api.voxburst.io/v1/posts \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello world from VoxBurst!",
    "accountIds": ["acc_123"]
  }'

Instagram requires media. If acc_123 is an Instagram account, a text-only post will fail. See Posting to Instagram below for the complete flow.

platforms vs accountIds — Two different fields, two different endpoints:

  • POST /v1/posts uses accountIds (an array of account IDs) to target where to post. The platform is inferred from each account.
  • POST /v1/posts/validate uses platforms (an array of platform constants like "TWITTER") to check content rules. It does not accept account IDs.

There is no platforms field on post creation or update. Always use accountIds to target accounts.

Schedule a Post

curl -X POST https://api.voxburst.io/v1/posts \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Scheduled post! 📅",
    "accountIds": ["acc_123", "acc_456"],
    "scheduledFor": "2026-03-01T14:00:00Z"
  }'

Per-platform content (platformOverrides)

Use platformOverrides to customize content per platform. The platform is still inferred from accountIds — overrides only change what gets posted, not where:

{
  "content": "Default content for all platforms",
  "accountIds": ["acc_123", "acc_456"],
  "platformOverrides": {
    "TWITTER": {
      "content": "Short version for Twitter! 🐦 #voxburst"
    },
    "LINKEDIN": {
      "content": "A longer, more professional version for LinkedIn. This is where you can really expand on your message and include more context for your professional network."
    }
  }
}

Publish Immediately

curl -X POST https://api.voxburst.io/v1/posts/{postId}/publish \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Platform Character Limits

VoxBurst validates content length before sending to each platform. The API returns a VALIDATION_ERROR if content exceeds platform limits.

PlatformMax TextMax ImagesVideo Length
Twitter/X280 chars42:20 min
LinkedIn3,000 chars2010 min
Instagram2,200 chars1090 sec
Facebook63,206 chars104 hours
Bluesky300 chars43 min
Threads500 chars105 min
YouTube5,000 chars012 hours
Mastodon500 chars45 min

Error Handling

All errors return a consistent JSON format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Content exceeds maximum length for Twitter (280 characters)",
    "details": {
      "field": "content",
      "platform": "TWITTER",
      "maxLength": 280,
      "actualLength": 312
    }
  }
}
HTTP StatusCodeDescription
400VALIDATION_ERRORInvalid request parameters
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENInsufficient permissions
404NOT_FOUNDResource not found
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Posting to Instagram

Instagram requires media on every post and a contentType to tell VoxBurst the format. The full flow is three steps: upload media, wait for it to be processed, then create the post.

Step 1 — Upload media and get a presigned URL

curl -X POST https://api.voxburst.io/v1/media/upload \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "photo.jpg",
    "contentType": "image/jpeg",
    "sizeBytes": 204800
  }'

Response:

{
  "mediaId": "media_abc1234567890abc12345678",
  "uploadUrl": "https://s3.amazonaws.com/...",
  "uploadHeaders": { "Content-Type": "image/jpeg" }
}

Step 2 — PUT your file directly to S3

curl -X PUT "https://s3.amazonaws.com/..." \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

Step 3 — Poll until status is READY

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

Poll every 2–3 seconds until the response shows "status": "READY". Then create the post:

Step 4 — Create the Instagram post

curl -X POST https://api.voxburst.io/v1/posts \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check this out! 📸",
    "accountIds": ["acc_instagram_123"],
    "contentType": "IMAGE",
    "media": ["media_abc1234567890abc12345678"],
    "firstComment": "#photography #voxburst"
  }'

Use contentType: "CAROUSEL" for 2–10 images/videos, "REEL" for short-form video, or "VIDEO" for a standard feed video. Always set contentType when posting to Instagram — omitting it may cause the post to be rejected.

If you have a publicly hosted image and don’t want to upload it yourself, use POST /v1/media/register to reference it by URL — VoxBurst stores the reference without re-hosting the file.

Next Steps

Last updated on
CLIHow agents use VoxBurst