Sign in
OpenAPI 3.1.0raw.githubusercontent.com2026-08-15140179507.6 KB

d3adfe49fbbf

Swarms

Create a persona

Creates one persona. To draft several with a model first, use POST /projects/{projectId}/personas/generate — that route persists nothing.

post/projects/{projectId}/personas

Headers

Idempotency-Keystring

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.

Request body

namestring required

1–120 characters.

rolestring required

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

notesstring

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

avatarShapeinteger

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.

avatarPaletteinteger

Index into the app's fixed palette set.

Response

The created persona.

idstring required

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

projectIdstring required
slugstring required

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

namestring required
rolestring required
notesstring nullable required
source'manual' | 'generated' | 'cluster' required

How the persona came to exist.

seedKeywordsstring[]

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

createdAtnumber required

Epoch milliseconds.

updatedAtnumber required

Epoch milliseconds.