Personas

A persona is a brand voice profile that governs the tone, style, and content strategy applied when generating posts with AI. Personas are made up of a profile (name, platform focus, linked social accounts) and modules (typed data blobs such as voice, pillars, visual_style, and audience). One persona can be marked as the workspace default.

When you set personaId on a post, the AI generation pipeline resolves the persona’s configuration to produce voice-consistent content for that platform.

Base URL

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

Using personaId on Posts

Pass personaId in the request body when creating or updating a post to apply a persona’s voice:

{
  "content": "Excited to share our latest update!",
  "accountIds": ["acc_123"],
  "personaId": "pp_abc123"
}

List Personas

GET /v1/personas

Returns all personas for the workspace.

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

Response (200):

{
  "personas": [
    {
      "id": "pp_abc123",
      "name": "TechBrand Voice",
      "description": "Professional tech-forward brand voice",
      "primaryPlatform": "x",
      "platforms": ["x", "linkedin"],
      "avatarUrl": null,
      "linkedAccountIds": ["acc_abc", "acc_def"],
      "isWorkspaceDefault": true,
      "createdAt": "2026-04-01T10:00:00Z",
      "updatedAt": "2026-04-20T14:00:00Z"
    }
  ]
}

Create Persona

POST /v1/personas/wizard

Required scopes: personas:write

Required feature: brand_voice (Pro plan or higher)

Creates a new persona. Initializes a profile, activates the first version, and writes any provided module data in a single call.

Request body:

The modules field lets you seed the persona’s voice configuration at creation time:

curl -X POST https://api.voxburst.io/v1/personas/wizard \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TechBrand Voice",
    "description": "Professional tech-forward brand voice",
    "primaryPlatform": "linkedin",
    "modules": {
      "voice": { "tone": "professional", "energy": "calm" },
      "pillars": { "topics": ["sustainability", "innovation"] }
    }
  }'

Response (201): Full persona profile including id.

Get Persona

GET /v1/personas/:id

Returns the full persona including its active version metadata and all configured modules.

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

Response (200):

{
  "id": "pp_abc123",
  "workspaceId": "ws_abc",
  "name": "TechBrand Voice",
  "description": "Professional tech-forward brand voice",
  "primaryPlatform": "linkedin",
  "platforms": ["linkedin", "x"],
  "avatarUrl": null,
  "linkedAccountIds": ["acc_abc", "acc_def"],
  "isWorkspaceDefault": false,
  "isComplete": true,
  "activeVersion": {
    "id": "pv_abc",
    "versionNumber": 1,
    "isActive": true,
    "createdAt": "2026-04-01T10:00:00Z"
  },
  "modules": [
    {
      "moduleType": "voice",
      "data": { "tone": "professional", "energy": "calm" },
      "schemaVersion": 1
    }
  ],
  "createdAt": "2026-04-01T10:00:00Z",
  "updatedAt": "2026-04-20T14:00:00Z"
}

A persona is considered ready for AI generation (isComplete: true) when its active version has at least one module configured.

Update Persona

PATCH /v1/personas/:id

Required scopes: personas:write

Updates mutable profile fields. When platforms is supplied without primaryPlatform, the first entry becomes the primary platform.

Request body:

curl -X PATCH https://api.voxburst.io/v1/personas/pp_abc123 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "platforms": ["x", "linkedin", "instagram"] }'

Set Default Persona

PATCH /v1/personas/:id/set-default

Required scopes: personas:write

Marks this persona as the workspace default. Automatically clears the default flag on any other persona. This operation is idempotent.

curl -X PATCH https://api.voxburst.io/v1/personas/pp_abc123/set-default \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

To retrieve the current default at any time: GET /v1/personas/default. Returns { "persona": null } if no default is set.

Delete Persona

DELETE /v1/personas/:id

Required scopes: personas:write

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

Returns 409 PERSONA_IN_USE if posts in the workspace still reference this persona. The response body includes linkedPostCount.

Duplicate Persona

POST /v1/personas/:id/duplicate

Required scopes: personas:write

Creates a full copy (profile + modules + memory) with a new ID. The copy’s name is prefixed with "Copy of ". Account links are not copied to the duplicate.

Response (201):

{ "personaId": "pp_new123" }

Modules

Modules are the typed data blobs that define how a persona behaves. Common module types are:

List Modules

GET /v1/personas/:id/modules

Returns all modules for the persona’s active version. Returns [] if no active version exists.

Write Module

PUT /v1/personas/:id/modules/:moduleType

Required scopes: personas:write

Creates or replaces a module on the active version.

Request body:

curl -X PUT https://api.voxburst.io/v1/personas/pp_abc123/modules/voice \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "tone": "conversational",
      "energy": "enthusiastic",
      "avoid": ["jargon", "passive voice"]
    }
  }'

Response (200):

{ "moduleType": "voice", "updated": true }

Account Links

A persona can be linked to one or more connected social accounts. When a post targets a linked account and has a personaId set, the runtime uses that persona’s voice configuration for generation.

List Linked Accounts

GET /v1/personas/:id/accounts

Returns { "accountIds": ["acc_abc", "acc_def"] }.

Link Account

POST /v1/personas/:id/accounts

Required scopes: personas:write

Request body:

{ "socialAccountId": "acc_abc123" }

Response (200): { "accountIds": [...] } — updated full list.

Unlink Account

DELETE /v1/personas/:id/accounts/:accountId

Required scopes: personas:write

Response (200): { "accountIds": [...] } — updated full list.

Export and Import

Personas can be exported as .vbpersona.json files and imported into any workspace.

Export

GET /v1/personas/:id/export

Returns a downloadable .vbpersona.json file. Add ?includeMemory=false to omit learned memory state (default: included).

Import

POST /v1/personas/import

Required scopes: personas:write

Accepts a .vbpersona.json body and creates a new persona in the current workspace. Module and memory arrays are capped at 50 and 20 entries respectively.

Response (201):

{ "personaId": "pp_new456" }

Narrative Arcs and Evolution

Personas support a narrative arc system for managing structured content storylines across posts (setup, conflict, resolution, and other stages), and an evolution system that adapts persona modules over time based on post performance signals.

Arc routes (GET /v1/personas/:id/arcs, POST /v1/personas/:id/arcs, etc.) require personas:write scope for write operations.

Evolution routes (POST /v1/personas/:id/evolution, GET /v1/personas/:id/evolution/state) require personas:write scope and the persona_evolution feature (Pro plan or higher).

Error Codes