Skip to Content
API ReferenceOpenAPI Spec

OpenAPI Spec

The VoxBurst API is fully described by an OpenAPI 3.1 spec. Use it to generate typed clients, validate requests, power IDE autocompletion, or import into API testing tools.

https://api.voxburst.io/api/openapi.yaml   # YAML
https://api.voxburst.io/api/openapi.json   # JSON

The spec reflects the live API. See Versioning & Compatibility for the guarantee: the API source code is ground truth, the spec is kept in sync with the implementation, and breaking changes are announced 30 days in advance.

Download

# Fetch YAML
curl -o voxburst.yaml https://api.voxburst.io/api/openapi.yaml
 
# Fetch JSON
curl -o voxburst.json https://api.voxburst.io/api/openapi.json

Generate a TypeScript client

openapi-typescript generates zero-runtime types directly from the spec. Pair it with openapi-fetch for a fully type-safe HTTP client.

npm install -D openapi-typescript openapi-fetch
npx openapi-typescript https://api.voxburst.io/api/openapi.yaml -o voxburst.d.ts

The generated types for the Post schema look like this:

// voxburst.d.ts (excerpt — generated from spec)
export interface components {
  schemas: {
    Post: {
      id: string                         // cuid2, e.g. "post_abc123"
      content: string
      contentType: 'TEXT' | 'IMAGE' | 'VIDEO' | 'CAROUSEL' | 'STORY' | 'REEL' | 'THREAD' | null
      status: 'draft' | 'scheduled' | 'publishing' | 'published' | 'partial' | 'failed' | 'cancelled' | 'unpublished'
      scheduledFor: string | null        // ISO 8601 UTC
      publishedAt: string | null
      firstComment: string | null
      firstCommentDelay: number | null
      tags: string[]
      metadata: Record<string, unknown> | null
      media: components['schemas']['MediaObject'][]
      platforms: components['schemas']['PlatformResult'][]
      threadPosts: components['schemas']['ThreadItem'][]
      personaId: string | null
      createdAt: string
      updatedAt: string
    }
    CreatePostInput: {
      content: string
      accountIds: string[]               // required — platform inferred from account
      contentType?: 'TEXT' | 'IMAGE' | 'VIDEO' | 'CAROUSEL' | 'STORY' | 'REEL' | 'THREAD'
      media?: string[]
      scheduledFor?: string
      saveAsDraft?: boolean
      queue?: boolean
      firstComment?: string
      firstCommentDelay?: number
      platformOverrides?: Record<string, { content?: string; media?: string[] }>
      tags?: string[]
      metadata?: Record<string, unknown>
      personaId?: string
      threadPosts?: components['schemas']['ThreadItem'][]
    }
    PlatformResult: {
      postPlatformId: string
      platform: string
      accountId: string
      accountName: string | null
      status: 'pending' | 'publishing' | 'published' | 'failed' | 'skipped'
      platformPostId: string | null
      platformPostUrl: string | null
      publishedAt: string | null
      error: { code: string; message: string } | null
    }
  }
}

Use with openapi-fetch for end-to-end type safety:

import createClient from 'openapi-fetch'
import type { paths } from './voxburst.d.ts'
 
const client = createClient<paths>({
  baseUrl: 'https://api.voxburst.io/v1',
  headers: { Authorization: `Bearer ${process.env.VOXBURST_API_KEY}` },
})
 
// Fully typed — IDE autocompletes fields, flags unknown keys at compile time
const { data, error } = await client.POST('/posts', {
  body: {
    content: 'Hello from a generated client!',
    accountIds: ['acc_abc123'],
    scheduledFor: '2026-07-01T15:00:00Z',
  },
})

Generate a Python client

openapi-generator-cli produces a full Python package with typed models and a requests-based client.

npx @openapitools/openapi-generator-cli generate \
  -i https://api.voxburst.io/api/openapi.yaml \
  -g python \
  -o ./voxburst-client \
  --additional-properties=packageName=voxburst_client,projectName=voxburst-client

Generated client usage:

import voxburst_client
from voxburst_client.api.posts_api import PostsApi
from voxburst_client.model.create_post_input import CreatePostInput
 
configuration = voxburst_client.Configuration(
    host="https://api.voxburst.io/v1",
    access_token=os.environ["VOXBURST_API_KEY"],
)
 
with voxburst_client.ApiClient(configuration) as api_client:
    api = PostsApi(api_client)
    post = api.create_post(CreatePostInput(
        content="Hello from the generated Python client!",
        account_ids=["acc_abc123"],
        scheduled_for="2026-07-01T15:00:00Z",
    ))
    print(f"Created: {post.id}")

Validate requests with Zod

openapi-zod-client generates Zod schemas directly from the spec — useful for validating request bodies before sending them to the API.

npx openapi-zod-client https://api.voxburst.io/api/openapi.yaml \
  -o voxburst-schemas.ts

The generated schema for CreatePostInput matches the API contract exactly:

// voxburst-schemas.ts (excerpt — matches API contract)
import { z } from 'zod'
 
export const CreatePostInputSchema = z.object({
  content: z.string().max(10_000),
  accountIds: z.array(z.string()).min(1),
  contentType: z.enum(['TEXT', 'IMAGE', 'VIDEO', 'CAROUSEL', 'STORY', 'REEL', 'THREAD']).optional(),
  media: z.array(z.string()).optional(),
  scheduledFor: z.string().datetime({ offset: true }).optional(),
  saveAsDraft: z.boolean().optional(),
  queue: z.boolean().optional(),
  firstComment: z.string().max(2200).optional(),
  firstCommentDelay: z.number().int().min(0).max(60).optional(),
  platformOverrides: z.record(z.object({
    content: z.string().optional(),
    media: z.array(z.string()).optional(),
  })).optional(),
  tags: z.array(z.string()).optional(),
  metadata: z.record(z.unknown()).optional(),
})
 
// Validate before sending
const result = CreatePostInputSchema.safeParse(inputFromUser)
if (!result.success) {
  console.error('Invalid post input:', result.error.flatten())
}

Postman & Insomnia

  1. Open Postman → Import
  2. Select Link and paste: https://api.voxburst.io/api/openapi.yaml
  3. Postman generates a collection with all endpoints pre-populated
  4. Set {{baseUrl}} to https://api.voxburst.io/v1 and {{apiKey}} to your key

Other tooling

ToolCommand
Redocly (hosted docs)npx @redocly/cli preview-docs https://api.voxburst.io/api/openapi.yaml
Go client (oapi-codegen)oapi-codegen -package voxburst -generate types,client voxburst.yaml > voxburst.gen.go
Mock server (Prism)npx @stoplight/prism-cli mock https://api.voxburst.io/api/openapi.yaml
Spectral lintnpx @stoplight/spectral-cli lint https://api.voxburst.io/api/openapi.yaml
Last updated on
MediaPersonas