Authentication

VoxBurst uses API key authentication. All requests require a Bearer token in the Authorization header.

API Keys

Authorization: Bearer vb_live_xxxxxxxxxxxxx

API keys are prefixed with vb_live_. Keys created in the VoxBurst dashboard always use this prefix.

Create and manage your API keys in the VoxBurst dashboard .

Scopes

API keys can be scoped to specific permissions. Use the minimum scopes required for your use case.

Rate Limiting

Rate limits are applied per API key based on your plan:

Rate limit information is returned in response headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1707753600

When rate limited, the API returns 429 Too Many Requests with a Retry-After header indicating when to retry.

Rate Limit Headers

Every API response includes headers to help you manage request pacing:

Example Response with Rate Limit Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1707753600
 
{
  "id": "post_abc123",
  "content": "Hello from VoxBurst!",
  "status": "scheduled"
}

Environment Variables

Store your API key as an environment variable:

# .env
VOXBURST_API_KEY=vb_live_xxxxxxxxxxxxx

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

Or with the TypeScript SDK:

import { VoxBurstClient } from '@voxburst/sdk'
const client = new VoxBurstClient({ apiKey: process.env.VOXBURST_API_KEY! })

Health Check

The API exposes two health endpoints under the /v1 prefix:

curl https://api.voxburst.io/v1/health

Both endpoints are unauthenticated and do not require an API key.

Resource ID Format

All VoxBurst resource IDs (post IDs, account IDs, etc.) follow the cuid2  format:

• Exactly 25 characters total
• Starts with the letter c
• Followed by 24 lowercase alphanumeric characters (a–z, 0–9)
• Example: cmp6v6bhf000369v60htcu3vc

Passing a malformed ID returns 400 Bad Request — not 404. The API validates the ID format before attempting a database lookup. Handle both 400 and 404 when an ID might be user-supplied:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid path parameter 'id': Invalid ID format"
  }
}

Idempotency

VoxBurst supports idempotency for all write operations (POST, PUT, PATCH, DELETE). This lets you safely retry requests on network failures without creating duplicate resources.

How to use

Add an Idempotency-Key header to any write request:

POST /v1/posts
Authorization: Bearer vb_live_xxxxxxxxxxxxx
Idempotency-Key: create-post-2026-06-01-campaign-a
Content-Type: application/json

Key format

Behavior

Response headers

Recommended key strategies

# Use a UUID per attempt
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
 
# Use a stable identifier for your operation
Idempotency-Key: schedule-post-campaign-123-slot-4
 
# Use a hash of the request intent for agent workflows
Idempotency-Key: post-${workspaceId}-${contentHash}-${scheduledFor}

Error codes

Contract precedence

When prose descriptions, inline examples, SDK documentation, and the OpenAPI spec ever appear to conflict, this ordering determines which source is authoritative:

1. API source code — the implementation is the ground truth. All other sources describe it.
2. This documentation — pages under /api-reference/* reflect the current implementation, validated against the codebase before publishing.
3. OpenAPI spec (GET /api/openapi.yaml) — machine-readable contract. Kept in sync with implementation; the source code takes precedence on conflict.
4. SDK docs (TypeScript, Go) — SDK method signatures and types are derived from the REST contract. Where SDK behavior diverges from REST, the REST contract wins.
5. Examples — illustrative, not normative. Examples may omit optional fields or use placeholder values.

In practice: if you encounter a mismatch between a docs example and a field table, trust the field table. If a field table conflicts with an actual API response, file a bug  — the implementation may have changed without a docs update.

Backwards compatibility: non-breaking changes (new optional fields, new endpoints, new enum values) are deployed without notice. Your client should ignore unknown fields. Breaking changes (field removal, type changes, endpoint removal) are announced at least 30 days in advance in the changelog.

Error Responses

Authentication failures return:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}