Calendar

Manage posts through VoxBurst’s content calendar and approval workflow: create and update calendar posts, submit them for approval, approve/reject, and publish. Also covers calendar personas (a separate, legacy persona system — see the callout below) and platform-to-calendar sync.

Base URL

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

Authentication: All endpoints require a Bearer token and workspace context, with the group’s schedule:read / schedule:write scopes. Some write endpoints additionally require an ADMIN or OWNER workspace role — noted per endpoint below.

List Calendar Posts

GET /v1/calendar/posts

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

Query Parameters

Get a Calendar Post

GET /v1/calendar/posts/:id

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

Returns { "data": <CalendarPost> }, or 404 if not found in the workspace.

Create a Calendar Post

POST /v1/calendar/posts

Request Body

curl -X POST https://api.voxburst.io/v1/calendar/posts \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_abc123",
    "content": "Draft for review",
    "platform": "TWITTER",
    "scheduledAt": "2026-09-01T15:00:00Z"
  }'

Returns { "data": <CalendarPost> } with 201.

Update a Calendar Post

PATCH /v1/calendar/posts/:id

All fields optional; only send what changes. Body fields mirror the create schema (content, scheduledAt, mediaId, imageUrl, notes, arc, personaId, status — each nullable where noted in the create schema).

curl -X PATCH https://api.voxburst.io/v1/calendar/posts/cmp6v6bhf000369v60htcu3vc \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Updated draft copy" }'

Submit for Approval

POST /v1/calendar/posts/:id/submit

Submits a calendar post into the approval workflow. Requires the calendar_approval_workflows plan feature.

Error Codes

Approve / Reject a Calendar Post

POST /v1/calendar/posts/:id/approve — requires ADMIN or OWNER role.

POST /v1/calendar/posts/:id/reject — requires ADMIN or OWNER role. Body: { "notes"?: string }.

curl -X POST https://api.voxburst.io/v1/calendar/posts/cmp6v6bhf000369v60htcu3vc/reject \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Please shorten the caption" }'

Error Codes

Publish a Calendar Post

POST /v1/calendar/posts/:id/publish — requires ADMIN or OWNER role.

Hands the calendar post off to VoxBurst’s publish pipeline.

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

Sync Posts from Platforms

POST /v1/calendar/sync

For each active connected account in the workspace whose platform adapter supports fetching historical posts (currently Mastodon and TikTok), imports recently published posts into the calendar and marks previously-tracked posts as UNPUBLISHED if they’ve been removed from the platform.

curl -X POST https://api.voxburst.io/v1/calendar/sync \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response

{
  "data": {
    "added": 3,
    "removed": 1,
    "unchanged": 46,
    "platforms": ["MASTODON"],
    "postsPerPlatform": 50
  }
}

Fix Duplicate Platform Records

POST /v1/calendar/fix-duplicate-platforms

Maintenance endpoint that de-duplicates internal records created by a sync run that executed twice concurrently. Safe to call repeatedly — returns 0 removed if there is nothing to fix.

curl -X POST https://api.voxburst.io/v1/calendar/fix-duplicate-platforms \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response

{ "data": { "removed": 2, "postPlatformRowsRemoved": 1, "duplicatePostsRemoved": 1 } }

Calendar Personas

List Personas

GET /v1/calendar/personas — requires the calendar_personas plan feature.

Get a Persona

GET /v1/calendar/personas/:id — requires the calendar_personas plan feature.

Create a Persona

POST /v1/calendar/personas — requires ADMIN/OWNER role and the calendar_personas plan feature.

Update a Persona

PATCH /v1/calendar/personas/:id — requires ADMIN/OWNER role and the calendar_personas plan feature.

Error Codes (all persona endpoints)