Skip to main content
POST
Create a persona

Authorizations

Authorization
string
header
required

MCPJam API key (sk_…). Create one at Settings → API keys. Guest sessions cannot use the API, and API keys cannot manage other API keys.

Headers

Idempotency-Key
string

Retry-safe create key. Replaying the SAME key with the SAME body returns the original resource instead of creating a second one; reusing it with a DIFFERENT body is a 409.

Path Parameters

projectId
string
required

ID of the hosted project that contains the server.

Body

application/json

The persona to create.

name
string
required

1–120 characters.

Maximum string length: 120
role
string
required

What this person is, in the product's terms — "finance ops lead", "first-time buyer". 1–120 characters.

Maximum string length: 120
notes
string

Free-text context the model is grounded in. Up to 2000 characters.

Maximum string length: 2000
avatarShape
integer

Index into the app's fixed shape set. Out of range is a 400 naming the field, not an upstream error about a constant you have never seen.

Required range: x >= 0
avatarPalette
integer

Index into the app's fixed palette set.

Required range: x >= 0

Response

The created persona.

A reusable synthetic character. The GOAL lives on the journey, not here — one persona can be pointed at many different tasks.

id
string
required

Durable id — what journeys reference and what every route here addresses.

projectId
string
required
slug
string
required

Stable slug key, shared with exported session data. Useful for correlating transcripts; NOT an address for this API.

name
string
required
role
string
required
notes
string | null
required
source
enum<string>
required

How the persona came to exist.

Available options:
manual,
generated,
cluster
avatar
object
required

Look, as indices into the app's fixed shape/palette sets. null when unset — the app then derives one from the id.

createdAt
number
required

Epoch milliseconds.

updatedAt
number
required

Epoch milliseconds.

seedKeywords
string[]

Present on cluster-derived personas: the terms the cluster was built from.