Prerequisites
- A person.run account with an active tenant.
- An API key from the dashboard (/dashboard/keys). Prefer a least-privilege profile and optional expiration for temporary access.
- curl or any HTTP client (fetch, httpie, Postman, etc.).
Step 1 — Set your API key
Grab your API key from the dashboard and export it so the examples below can reference it.
export PERSON_API_KEY="your_api_key_here"
export PERSON_TENANT_ID="your-tenant-id"Step 2 — Create a persona
Create a persona by providing a seed — the basic biographical facts that person.run uses to generate a full personality profile. At minimum you need a first name, last name, age, location, and base occupation.
curl -X POST https://api.person.run/personas \
-H "x-api-key: $PERSON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tenantId": "'$PERSON_TENANT_ID'",
"seed": {
"firstName": "Aria",
"lastName": "Chen",
"age": 32,
"location": "San Francisco",
"baseOccupation": "Product designer"
}
}'The response includes the full persona object with a generated summary, a UUID you'll use for all subsequent calls, and an initial timeline memory.
{
"persona": {
"id": "a1b2c3d4-...",
"tenantId": "your-tenant-id",
"firstName": "Aria",
"lastName": "Chen",
"age": 32,
"location": "San Francisco",
"baseOccupation": "Product designer",
"summary": "Aria Chen, 32, based in San Francisco, works as Product designer.",
"createdAt": "2026-02-20T12:00:00.000Z",
"updatedAt": "2026-02-20T12:00:00.000Z"
}
}Save the persona id for the next step.
export PERSONA_ID="a1b2c3d4-..."Step 3 — Prompt the persona
Send a prompt and get a response that reflects the persona's identity, background, and memories.
curl -X POST https://api.person.run/personas/prompt \
-H "x-api-key: $PERSON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tenantId": "'$PERSON_TENANT_ID'",
"personaId": "'$PERSONA_ID'",
"userPrompt": "How do you approach design challenges?"
}'{
"prompt": "How do you approach design challenges?",
"response": "I usually start by sitting with the problem for a while...",
"sessionId": "sess-uuid-..."
}Step 4 — Add a memory
Enrich the persona by appending a timeline memory. This shapes how the persona responds to future prompts — memories with higher strength surface more readily.
curl -X POST https://api.person.run/personas/$PERSONA_ID/timeline \
-H "x-api-key: $PERSON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tenantId": "'$PERSON_TENANT_ID'",
"eventAt": "2025-06-15T10:00:00.000Z",
"eventLabel": "Won a design award",
"facts": "Received the IDSA Gold Award for a healthcare dashboard redesign.",
"feelings": "Proud and validated after months of intensive research.",
"emotionTags": ["pride", "accomplishment"],
"memoryType": "pride",
"memoryStrength": 88,
"interpretation": "This reinforced my belief that user research is worth the investment."
}'Now when you prompt the persona about design accomplishments, this memory will surface naturally in the response.
Step 5 — Check consistency
As your persona accumulates memories, run a consistency check to catch contradictions or timeline issues.
curl https://api.person.run/personas/$PERSONA_ID/consistency\?tenantId=$PERSON_TENANT_ID \
-H "x-api-key: $PERSON_API_KEY"{
"report": {
"personaId": "a1b2c3d4-...",
"checkedAt": "2026-02-20T12:05:00.000Z",
"issueCount": 0,
"issues": []
}
}