Accounts

Connect and manage social media accounts. VoxBurst supports OAuth-based account connection for all major platforms.

Base URL

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

List Accounts

GET /v1/accounts

List all connected social media accounts.

Query Parameters

curl "https://api.voxburst.io/v1/accounts?status=ACTIVE&platform=twitter" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": "acc_123",
      "platform": "twitter",
      "username": "@voxburst",
      "displayName": "VoxBurst",
      "avatarUrl": "https://cdn.example.com/avatar.jpg",
      "accountType": "personal",
      "status": "active",
      "connectedAt": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "limit": 20
  }
}

The list is paginated using cursor-based pagination. Pass cursor=<nextCursor> as a query parameter to fetch the next page.

Connect Account

POST /v1/accounts/connect/:platform

Initiate OAuth connection for a social media platform. Returns an authorization URL to redirect the user to.

Required scopes: accounts:write

Supported platforms: twitter, linkedin, instagram, facebook, bluesky, threads, youtube, mastodon, tiktok, pinterest, snapchat, reddit, telegram, googlebusiness, whatsapp

Request Body

curl -X POST https://api.voxburst.io/v1/accounts/connect/linkedin \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUrl": "https://yourapp.com/oauth/callback",
    "pageMode": true
  }'

Response

{
  "authorizationUrl": "https://x.com/i/oauth2/authorize?...",
  "state": "oauth_state_token"
}

OAuth Callback

POST /v1/accounts/callback/:platform

Complete the OAuth flow by exchanging the authorization code for access tokens.

Required scopes: accounts:write

curl -X POST https://api.voxburst.io/v1/accounts/callback/twitter \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "oauth_authorization_code",
    "state": "oauth_state_token"
  }'

Response

{
  "account": {
    "id": "acc_789",
    "platform": "twitter",
    "username": "@newuser",
    "displayName": "New User",
    "status": "active",
    "connectedAt": "2026-02-20T10:00:00Z"
  }
}

Disconnect Account

DELETE /v1/accounts/:id

Disconnect and remove a social media account.

Required scopes: accounts:write

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

Response (200):

{ "success": true }

Refresh Account Token

POST /v1/accounts/:id/refresh

Manually refresh the OAuth token for an account. VoxBurst refreshes tokens automatically, but this endpoint is available for troubleshooting.

Required scopes: accounts:write

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

Response (200):

{ "success": true }

Test Connection

POST /v1/accounts/:id/test

Test the connection for a social account by making a lightweight API call to the platform.

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

Response

{
  "success": true,
  "message": "Connection verified"
}

On success, some platforms return additional details:

{
  "success": true,
  "message": "Connection verified",
  "details": {
    "platformUserId": "1234567890",
    "username": "@voxburst",
    "displayName": "VoxBurst"
  }
}

Get Account

GET /v1/accounts/:id

Retrieve a single connected account by ID.

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

List Pages

GET /v1/accounts/:id/pages

List the pages or business accounts associated with a connected account. Currently supported for LinkedIn and Instagram (Facebook Login) accounts.

• LinkedIn: Returns the organizations the connected user administers. Use these to populate a page selector before creating a LinkedIn post targeting a company page.
• Instagram (Facebook Login only): Returns the Instagram Business accounts linked to the connected Facebook user token. Accounts connected via Instagram Direct Login (oauthVersion: "instagram_login") return an empty pages array — only Facebook Login-connected accounts (oauthVersion: "fb_login") have access to page data.

For all other platforms, returns an empty pages array.

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

Response — LinkedIn

{
  "pages": [
    {
      "id": "page_001",
      "name": "VoxBurst Official",
      "urn": "urn:li:organization:12345678",
      "type": "organization",
      "logoUrl": "https://cdn.example.com/logo.png"
    }
  ]
}

Response — Instagram

{
  "pages": [
    {
      "id": "<ig_user_id>",
      "name": "@username",
      "pageId": "<fb_page_id>",
      "pageName": "Page Display Name",
      "type": "instagram",
      "avatarUrl": "https://..."
    }
  ]
}

Select Page

POST /v1/accounts/:id/select-page

Persist a page selection for an account. Supported for LinkedIn and Instagram accounts.

• LinkedIn: Saves the selected LinkedIn Page. Subsequent posts to this account are published to the selected page.
• Instagram (Facebook Login only): Re-fetches Instagram Business accounts from the Graph API, matches on pageId, and updates the account with username, instagramAccountId, pageAccessToken, pageId, pageName, and oauthVersion: 'fb_login'. Returns 400 INVALID_PAGE_ID if the provided pageId is not found among the accounts accessible via the connected Facebook token.

Required scopes: accounts:write

Request Body

# LinkedIn example
curl -X POST https://api.voxburst.io/v1/accounts/acc_123/select-page \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "pageId": "page_001", "pageName": "VoxBurst Official" }'
 
# Instagram example
curl -X POST https://api.voxburst.io/v1/accounts/acc_456/select-page \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "pageId": "<fb_page_id>", "pageName": "Page Display Name" }'

Error Codes

Page ownership

Each Page or Instagram Business account is stored as its own connected account. A Page may only be selected onto the account it actually belongs to — POST /v1/accounts/:id/select-page verifies ownership before writing and returns 400 ACCOUNT_PAGE_MISMATCH when the selected Page belongs to a different account. Nothing is written when this error is returned; the account is left exactly as it was.

This applies in three situations:

• Instagram — the pageId resolves to a different Instagram Business account than the one identified by :id.
• Instagram — the platform does not report the selected Page as the owner of this account’s Instagram Business account. This can happen if the Page↔account link changed on the platform after the account was connected.
• Facebook — the account is already keyed to a specific Page, or the selected Page is already stored as its own connected account in the workspace.

What a client should do: re-fetch GET /v1/accounts/:id/pages and retry with a Page belonging to that account. Retrying with the same pageId will fail identically — this is not a transient condition. If the Page you want is administered by the same user but belongs to a different account, manage it through that account’s own id rather than reassigning this one. If neither applies, reconnect the account to refresh the Page↔account relationships.

YouTube Playlists

GET /v1/accounts/:id/youtube/playlists

Returns the YouTube playlists accessible by a connected YouTube account. Use this to populate a playlist selector before creating a YouTube post.

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

Response (200)

{
  "playlists": [
    { "id": "PLxxxxxxxxxxxxxxxxxx", "title": "My Tutorial Series" },
    { "id": "PLyyyyyyyyyyyyyyyyyy", "title": "Product Demos" }
  ]
}

If the connected account does not have the YouTube playlist read scope, the response returns an empty list with a requiresReauth flag:

{
  "playlists": [],
  "requiresReauth": true
}

When requiresReauth is true, prompt the user to reconnect their YouTube account to grant the required scope.

TikTok Creator Info

GET /v1/accounts/:id/tiktok/creator-info

Returns TikTok’s creator info for a connected TikTok account — the connected creator’s nickname, the privacy levels they’re allowed to post with, and their duet/stitch/comment interaction settings. TikTok’s Content Sharing Guidelines require this to be fetched and rendered before a “Post to TikTok” screen is shown: the privacy options offered must exactly match privacyLevelOptions, and the duet/stitch/comment toggles must be disabled wherever the creator has turned those interactions off on their own account.

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

Response (200) — available

{
  "available": true,
  "creatorInfo": {
    "nickname": "jane.creates",
    "username": "jane.creates",
    "avatarUrl": "https://p16-sign.tiktokcdn.com/...",
    "privacyLevelOptions": ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "SELF_ONLY"],
    "commentDisabled": false,
    "duetDisabled": false,
    "stitchDisabled": true,
    "maxVideoPostDurationSec": 600,
    "canPost": true
  }
}

Response (200) — unavailable

{
  "available": false,
  "reason": "NO_TOKEN"
}

Response Fields

Account Backfill

Get Backfill Status

GET /v1/accounts/:id/backfill

Get the backfill status for a connected account. Backfill pulls historical analytics from the platform.

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

Trigger Backfill

POST /v1/accounts/:id/backfill

Trigger a historical analytics backfill for a connected account.

Required scopes: accounts:write

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

Optimal Posting Times

GET /v1/accounts/:id/optimal-times

Returns the optimal posting time slots for a connected account based on historical engagement data.

Query Parameters

curl "https://api.voxburst.io/v1/accounts/acc_123/optimal-times?timezone=America/New_York&limit=5" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Instagram Audio Search

GET /v1/instagram/audio/search

Search for audio tracks available for use in Instagram Reels. Returns trending tracks when q is omitted, or filtered results when a search term is provided.

Auth: Bearer token required (read:posts scope)

Query Parameters

# Trending tracks
curl "https://api.voxburst.io/v1/instagram/audio/search?accountId=acc_456&limit=10" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"
 
# Search by term
curl "https://api.voxburst.io/v1/instagram/audio/search?accountId=acc_456&q=summer&limit=20" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response (200)

{
  "tracks": [
    {
      "id": "1234567890",
      "title": "Track Title",
      "artistName": "Artist Name",
      "audioUrl": "https://...",
      "coverImageUri": "https://...",
      "durationMs": 30000
    }
  ]
}

Response Fields

Error Codes

Google Business Profile Locations

Connected Google Business Profile accounts can have multiple business locations. Use these endpoints to list available locations and configure which ones are selected for posting.

List GMB Locations

GET /v1/accounts/:id/gmb/locations

Returns all GMB locations available under a connected Google Business account, grouped by account, with each location’s current selection state.

Auth: Bearer token, workspace-scoped. The account identified by :id must be a GOOGLE_BUSINESS platform account.

curl https://api.voxburst.io/v1/accounts/acc_example123/gmb/locations \
  -H "Authorization: Bearer eyJexample..."

Response (200)

{
  "groups": [
    {
      "accountName": "Acme Corp",
      "accountPath": "accounts/123456789",
      "locations": [
        {
          "path": "accounts/123456789/locations/987654321",
          "title": "Acme Corp - Main St",
          "address": "123 Main St, Springfield, IL 62701",
          "selected": true
        },
        {
          "path": "accounts/123456789/locations/111222333",
          "title": "Acme Corp - Oak Ave",
          "address": "456 Oak Ave, Springfield, IL 62702",
          "selected": false
        }
      ]
    }
  ],
  "selectedCount": 1
}

Response Fields

Error Codes

Save GMB Location Selection

PUT /v1/accounts/:id/gmb/locations

Saves the set of selected location paths for a connected GMB account. Only the locations listed in locationPaths will be marked as selected; all others will be deselected.

Auth: Bearer token, workspace-scoped. Requires accounts:write scope.

Request Body

curl -X PUT https://api.voxburst.io/v1/accounts/acc_example123/gmb/locations \
  -H "Authorization: Bearer eyJexample..." \
  -H "Content-Type: application/json" \
  -d '{
    "locationPaths": [
      "accounts/123456789/locations/987654321"
    ]
  }'

Response (200)

{
  "success": true,
  "selectedCount": 1
}

Error Codes

Shared Accounts

When the same social media account (identified by platform + platform user ID) is connected in more than one VoxBurst workspace, VoxBurst marks it as a shared account. Posts published from any workspace that share the account count toward a combined platform publishing limit.

When you connect an account that is already connected in another workspace, the connect response includes a warning:

{
  "account": { "id": "acc_789", "platform": "instagram", "username": "brandname", ... },
  "warning": "This account is already connected in another workspace. Posts to this account from all connected workspaces share a combined publishing limit."
}

The isSharedAccount field on the account record is true when this condition applies.

Account Fields

All string enum fields (platform, status, accountType) are returned as lowercase strings in REST API responses.

Scope Health

When an account is connected or reconnected, VoxBurst compares the permissions the platform actually granted against the permissions each VoxBurst feature requires for that platform, and records the result on the account as scopeHealth.

This exists because a connection can succeed, and publishing can work, while a narrower operation on the same account cannot — the shortfall is otherwise invisible until a user attempts that operation. scopeHealth lets an integration surface the shortfall at connect time instead.

{
  "id": "acc_123",
  "platform": "instagram",
  "status": "active",
  "scopeHealth": {
    "status": "DEGRADED",
    "degradedCapabilities": [
      { "capability": "deletePost", "label": "deleting posts" }
    ],
    "message": "This connection is missing permissions for deleting posts. Reconnect the account and accept all requested permissions to restore it.",
    "verifiedAt": "2026-08-21T14:02:11.000Z"
  }
}

Fields

Note that scopeHealth never contains raw platform permission names. Branch on capability; display label or message.

Status values

Capability keys

New capability keys may be added over time. Treat an unrecognised capability as a generic degradation and fall back to displaying label.

Account Status

All status and platform values in REST API responses are lowercase strings (e.g. "twitter", "active"). This applies to all account endpoints: list, get, connect callback, refresh, and test.

Query parameters that filter by status or platform accept UPPERCASE values (e.g. status=ACTIVE, platform=TWITTER). The response always returns lowercase regardless of how the query parameter was cased.

Webhook payloads (account.connected, account.error) use UPPERCASE for platform and status — this is intentionally different from REST responses. See Webhooks for details.

OAuth Edge Cases

Reconnecting an already-connected account

If a user completes the OAuth flow for an account that is already connected in the same workspace (same platform + platform user ID), VoxBurst upserts the account record: tokens are refreshed, status is reset to ACTIVE, and any previous errors are cleared. No duplicate account is created.

Connecting an account that exists in another workspace

When the same social account is connected across multiple workspaces, VoxBurst flags it as a shared account. The callback response includes a warning field:

{
  "account": { "id": "acc_789", "platform": "instagram", ... },
  "warning": "This account is already connected in another workspace. Posts to this account from all connected workspaces share a combined publishing limit."
}

OAuth state expiry

The OAuth state token stored during the connect step expires after 10 minutes. If the user does not complete authorization within that window, the callback endpoint will return:

{ "error": { "code": "INVALID_PARAM", "message": "Invalid or expired OAuth state" } }

Restart the connect flow to get a fresh state token.

OAuth error codes

Instagram OAuth result error codes

When an Instagram OAuth attempt fails, the callback redirect includes an errorCode query parameter on the result page. These codes are distinct from the API error codes above — they are propagated via the redirect URL rather than a JSON error response. Integrations that present or process the OAuth result URL should handle these values:

Token expiry and refresh

VoxBurst refreshes tokens automatically when they are within 5 minutes of expiry. If automatic refresh fails (e.g. the user revoked access), the account status is set to EXPIRED or ERROR. At that point:

• Call POST /v1/accounts/:id/refresh to attempt a manual refresh
• If refresh fails, the user must reconnect via the full OAuth flow

Bluesky and Mastodon accounts do not use expiring tokens and do not require refresh.

Instagram OAuth Paths

VoxBurst supports two active OAuth paths for connecting Instagram accounts. The path used is recorded in the oauthVersion field on the account and governs which API scopes and endpoints are available.

API behavior: POST /v1/accounts/connect/instagram always initiates the Facebook Login for Business (FLOB) path. There is no loginMethod parameter — the login path is not selectable via the API. Direct Login is the default in the VoxBurst app UI but is not available to API callers.

Checking FLOB eligibility

For Instagram accounts connected via Direct Login, VoxBurst runs an eligibility check after connection and writes the result to the flobProbe field. You can read this field from GET /v1/accounts/:id:

{
  "id": "acc_example123",
  "platform": "instagram",
  "oauthVersion": "instagram_login",
  "flobProbe": {
    "flobAvailable": true,
    "facebookAccountId": "...",
    "checkedAt": "2026-07-06T01:29:37Z"
  }
}

flobProbe may be absent if the check has not yet completed. If you need to wait for it, poll GET /v1/accounts/:id — the field will be populated within a few seconds of account connection.

Feature availability by OAuth path

Some Instagram-specific endpoints require a Facebook Login-connected account (i.e. oauthVersion: "fb_login"):

User Endpoints

Store GA4 Client ID

POST /v1/users/me/ga4-client-id

Stores the browser-side GA4 client ID for server-side Measurement Protocol event stitching. Call this once per session after the GA4 client ID becomes available in the browser (typically via gtag('get', ...) or ga.getAll()[0].get('clientId')).

Auth: Bearer token required

Request Body

curl -X POST https://api.voxburst.io/v1/users/me/ga4-client-id \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "clientId": "1234567890.9876543210" }'

Response (200)

{ "ok": true }

Error Codes