POST
/
v1
/
teams
/
{teamId}
/
personas
TypeScript client
import { OctosparkClient } from '@octospark/sdk'

const client = new OctosparkClient({
  token: process.env.OCTOSPARK_TOKEN
})

const response = await client.personas.createPersona({
  teamId: process.env.OCTOSPARK_TEAM_ID ?? "teamId",
  body: {},
})
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "displayName": "<string>",
  "dateOfBirth": "<string>",
  "biography": "<string>",
  "careerExperiences": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "title": "<string>",
      "summary": "<string>",
      "isCurrent": true,
      "organization": "<string>",
      "industry": "<string>",
      "startedAt": "<string>",
      "endedAt": "<string>"
    }
  ],
  "avatarAttributes": {},
  "selectedElevenLabsVoiceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "revision": 123,
  "archivedAt": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
idempotency-key
string

Reuse this key and the original body after a lost response. Changed requests return 409. For generated creation, this header must match the payload idempotencyKey.

Required string length: 1 - 512

Path Parameters

​
teamId
string
required

Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context.

Body

application/json
​
mode
enum<string>
required
Available options:
generated
​
origin
enum<string>
required
Available options:
synthetic_person
​
profile
object
required
​
idempotencyKey
string
required

a string at most 512 character(s) long

Required string length: 1 - 512
​
selectedElevenLabsVoiceId
string<uuid> | null

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
referenceAssets
maxItems(100) · object[]

an array of at most 100 item(s)

Maximum array length: 100
​
modelId
string

Persona image requests use google/gemini-3.1-pro-image. Omit modelId or provide that value. New requests for another model are rejected before setup or generation; matching accepted requests retain their original replay behaviour.

Required string length: 1 - 512

Response

Success

​
id
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
teamId
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
origin
enum<string>
required
Available options:
real_person,
synthetic_person
​
displayName
string
required
​
dateOfBirth
string
required

a string matching the pattern ^\d{4}-\d{2}-\d{2}$

Pattern: ^\d{4}-\d{2}-\d{2}$
​
biography
string
required
​
careerExperiences
maxItems(100) · object[]
required

an array of at most 100 item(s)

Maximum array length: 100
​
avatarAttributes
object
required
​
selectedElevenLabsVoiceId
string<uuid> | null
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
revision
integer
required

an integer

​
archivedAt
string | null
required
​
createdAt
string
required
​
updatedAt
string
required