Skip to main content

Personas API

REST endpoints for managing personas. Personas define a description and system prompt for test scenarios.

Endpoints​

MethodEndpointDescription
GET/api/projects/:projectId/personasList personas
POST/api/projects/:projectId/personasCreate a persona
GET/api/projects/:projectId/personas/:idGet a persona by ID
PUT/api/projects/:projectId/personas/:idUpdate a persona
DELETE/api/projects/:projectId/personas/:idDelete a persona
POST/api/projects/:projectId/personas/:id/generate-imageGenerate AI portrait

GET /api/projects/:projectId/personas​

List all personas.

Response (200 OK)​

[
{
"id": "987fcdeb-51a2-3bc4-d567-890123456789",
"name": "impatient-user",
"description": "A user who wants quick answers",
"systemPrompt": "You are an impatient user who values brevity and expects quick, concise responses.",
"createdAt": "2026-01-28T10:00:00.000Z",
"updatedAt": "2026-01-28T10:00:00.000Z"
}
]

Example​

curl http://localhost:3000/api/projects/PROJECT_ID/personas

POST /api/projects/:projectId/personas​

Create a new persona.

Request Body​

FieldTypeRequiredDescription
namestringYesPersona name
descriptionstringNoShort description of the persona
systemPromptstringNoFull description / system prompt for this persona
headersobjectNoHTTP headers merged with connector headers (persona headers take precedence)
{
"name": "impatient-user",
"description": "A user who wants quick answers",
"systemPrompt": "You are an impatient user who values brevity and expects quick, concise responses.",
"headers": { "X-User-Language": "en" }
}

Response (201 Created)​

{
"id": "987fcdeb-51a2-3bc4-d567-890123456789",
"name": "impatient-user",
"description": "A user who wants quick answers",
"systemPrompt": "You are an impatient user who values brevity and expects quick, concise responses.",
"createdAt": "2026-01-28T10:00:00.000Z",
"updatedAt": "2026-01-28T10:00:00.000Z"
}

Errors​

StatusDescription
400Name is required
409Persona with name already exists

Example​

curl -X POST http://localhost:3000/api/projects/PROJECT_ID/personas \
-H "Content-Type: application/json" \
-d '{
"name": "impatient-user",
"description": "A user who wants quick answers",
"systemPrompt": "You are an impatient user who values brevity and expects quick, concise responses."
}'

GET /api/projects/:projectId/personas/:id​

Get a persona by its ID.

Response (200 OK)​

{
"id": "987fcdeb-51a2-3bc4-d567-890123456789",
"name": "impatient-user",
"description": "A user who wants quick answers",
"systemPrompt": "You are an impatient user who values brevity and expects quick, concise responses.",
"createdAt": "2026-01-28T10:00:00.000Z",
"updatedAt": "2026-01-28T10:00:00.000Z"
}

Errors​

StatusDescription
404Persona not found

Example​

curl http://localhost:3000/api/projects/PROJECT_ID/personas/987fcdeb-51a2-3bc4-d567-890123456789

PUT /api/projects/:projectId/personas/:id​

Update an existing persona.

Request Body​

FieldTypeRequiredDescription
namestringNoNew persona name
descriptionstringNoNew short description
systemPromptstringNoNew system prompt
imageUrlstringNoImage ID referencing a stored image
headersobjectNoHTTP headers merged with connector headers (persona headers take precedence)
{
"systemPrompt": "You are a technical user who expects detailed, accurate responses."
}

Response (200 OK)​

{
"id": "987fcdeb-51a2-3bc4-d567-890123456789",
"name": "impatient-user",
"description": "A user who wants quick answers",
"systemPrompt": "You are a technical user who expects detailed, accurate responses.",
"createdAt": "2026-01-28T10:00:00.000Z",
"updatedAt": "2026-01-28T10:30:00.000Z"
}

Errors​

StatusDescription
404Persona not found
409Persona with name already exists

Example​

curl -X PUT http://localhost:3000/api/projects/PROJECT_ID/personas/987fcdeb-51a2-3bc4-d567-890123456789 \
-H "Content-Type: application/json" \
-d '{"systemPrompt": "You are a technical user who expects detailed, accurate responses."}'

DELETE /api/projects/:projectId/personas/:id​

Delete a persona.

Response (204 No Content)​

Empty response on success.

Errors​

StatusDescription
404Persona not found

Example​

curl -X DELETE http://localhost:3000/api/projects/PROJECT_ID/personas/987fcdeb-51a2-3bc4-d567-890123456789

POST /api/projects/:projectId/personas/:id/generate-image​

Generate an AI portrait image for a persona using OpenAI's gpt-image-1 model. The image is generated from the persona's systemPrompt and optionally styled to match the project's style reference images.

Requires an OpenAI LLM provider configured in project settings.

Response (200 OK)​

Returns the updated persona with imageUrl set to the generated image ID.

{
"id": "987fcdeb-51a2-3bc4-d567-890123456789",
"name": "impatient-user",
"description": "A user who wants quick answers",
"systemPrompt": "You are an impatient user who values brevity...",
"imageUrl": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.png",
"createdAt": "2026-01-28T10:00:00.000Z",
"updatedAt": "2026-01-28T10:30:00.000Z"
}

Errors​

StatusDescription
400Persona has no system prompt
400No LLM provider configured
400LLM provider is not OpenAI
404Persona not found

Example​

curl -X POST http://localhost:3000/api/projects/PROJECT_ID/personas/987fcdeb/generate-image