Documentation

Build with person.run

Everything you need to go from idea to deployed persona. Guides, API reference, and SDK docs.

Quick start

Get your API key

bash

# Create an API key from the dashboard at /dashboard/keys
# Then set it in your environment:
export PERSON_API_KEY=your_api_key_here

Create a persona

bash

curl -X POST https://api.person.run/personas \
  -H "x-api-key: $PERSON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "your-tenant-id",
    "seed": {
      "firstName": "Aria",
      "lastName": "Chen",
      "age": 32,
      "location": "San Francisco",
      "baseOccupation": "Product designer"
    }
  }'

Send a prompt

bash

curl -X POST https://api.person.run/personas/prompt \
  -H "x-api-key: $PERSON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "your-tenant-id",
    "personaId": "persona-uuid",
    "userPrompt": "How do you approach design challenges?"
  }'

Guides & references

Introduction

What person.run is, core concepts, and the mental model behind AI personas.

Concepts reference

Full reference docs for personas, skills, cohorts, populations, and studies.

Quick start

Create and prompt your first persona in under 5 minutes.

Organizations & SSO

Set up Clerk organizations, team roles, and SAML SSO for enterprise workspaces.

REST API

Full interactive API reference generated from the OpenAPI spec.

Streaming

Stream persona responses token-by-token with Server-Sent Events.

Embed widget

Drop a persona chat widget into any web page with a few lines of code.

Guardrails

Configure content safety, topic boundaries, and escalation triggers.

Analytics

Track conversation events, monitor usage, and export data.

Timeline & Memory

Memory types, strength, revision, and consistency checking.

Model catalog

Auto-generated model reference pages from AI Gateway with stable slugs.

Model pricing matrix

Compare input/output/image pricing across all discovered models, plus prompt-settlement notes for flat tool invocation billing.

Automation + Surveys

Configure managed automation and survey delivery workflows from first-party surfaces.

TypeScript SDK

Type-safe SDK with autocomplete support.

Python SDK

Idiomatic Python client for server-side apps.

R SDK

Researcher-friendly client for statistical workflows.

Concept reference

Deep, operational documentation for each core concept in the synthetic research workflow.

Persona

A durable synthetic individual

A persona is the identity anchor for all research interactions: stable profile, evolving memory, and consistent voice.

Open concept docs

Skill

A reusable research task

A skill defines what you ask and how you evaluate it, so prompt execution can be repeated across personas and studies.

Open concept docs

Cohort

A targeted segment within your audience

A cohort groups personas with shared attributes so you can reason about segment-specific behavior before scaling to full populations.

Open concept docs

Population

A complete synthetic panel

A population combines cohorts into a balanced audience model you can run repeatable studies against at scale.

Open concept docs

Study

A controlled run across a population

A study binds a skill to a target population, runs at scale, and returns structured evidence for product decisions.

Open concept docs

REST API reference

Base URL: https://api.person.run · Authenticate with x-api-key: <key>

GET/personasList personas by tenant

POST/personasCreate persona from seed

GET/personas/:personaIdGet a single persona

PATCH/personas/:personaIdUpdate persona fields

DELETE/personas/:personaIdDelete a persona

GET/personas/:personaId/exportExport persona data

POST/personas/promptPrompt a persona (sync/async)

POST/personas/prompt/streamStream persona response (SSE)

GET/personas/prompt/jobs/:jobIdPoll async job status

GET/personas/prompt/sessionsList recent prompt sessions

GET/personas/:personaId/timelineGet persona timeline

POST/personas/:personaId/timelineAppend timeline memory

POST/personas/:personaId/timeline/:timelineId/supersedeSupersede a timeline entry

GET/personas/:personaId/consistencyRun consistency check

GET/personas/safety-policyGet tenant safety policy

PUT/personas/safety-policyUpsert safety policy

DELETE/personas/safety-policy/:tenantIdRemove safety policy

GET/skillsList skill definitions

POST/skillsCreate a skill definition

GET/tasksList task executions

GET/tasks/:taskIdGet task execution detail

PATCH/tasks/:taskId/controlPause/resume/cancel task execution

POST/tasks/:taskId/executeQueue task execution

GET/schedulesList schedules

POST/schedulesCreate one-time or recurring schedule

POST/schedules/:scheduleId/trigger-nowTrigger schedule immediately

GET/studiesList studies

POST/studiesCreate a study

POST/studies/:studyId/runsStart a study run

GET/healthHealth check with dependency status

GET/openapi.jsonOpenAPI specification

SDKs

REST API

stable

# No installation needed — use any HTTP client
curl https://api.person.run/health

OpenAPI Spec

stable

# Import into Postman, Insomnia, or any OpenAPI tool
curl https://api.person.run/openapi.json

TypeScript SDK

stable

npm install @person.run/sdkDownload .zip

Python SDK

stable

pip install person-sdkDownload .zip

R SDK

stable

devtools::install_github("person-run/person.run",
  subdir = "packages/sdk-r")

Download .zip

Documentation

Build with person.run

Everything you need to go from idea to deployed persona. Guides, API reference, and SDK docs.

Quick start

Get your API key

bash

# Create an API key from the dashboard at /dashboard/keys
# Then set it in your environment:
export PERSON_API_KEY=your_api_key_here

Create a persona

bash

curl -X POST https://api.person.run/personas \
  -H "x-api-key: $PERSON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "your-tenant-id",
    "seed": {
      "firstName": "Aria",
      "lastName": "Chen",
      "age": 32,
      "location": "San Francisco",
      "baseOccupation": "Product designer"
    }
  }'

Send a prompt

bash

curl -X POST https://api.person.run/personas/prompt \
  -H "x-api-key: $PERSON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "your-tenant-id",
    "personaId": "persona-uuid",
    "userPrompt": "How do you approach design challenges?"
  }'

Guides & references

Introduction

What person.run is, core concepts, and the mental model behind AI personas.

Concepts reference

Full reference docs for personas, skills, cohorts, populations, and studies.

Quick start

Create and prompt your first persona in under 5 minutes.

Organizations & SSO

Set up Clerk organizations, team roles, and SAML SSO for enterprise workspaces.

REST API

Full interactive API reference generated from the OpenAPI spec.

Streaming

Stream persona responses token-by-token with Server-Sent Events.

Embed widget

Drop a persona chat widget into any web page with a few lines of code.

Guardrails

Configure content safety, topic boundaries, and escalation triggers.

Analytics

Track conversation events, monitor usage, and export data.

Timeline & Memory

Memory types, strength, revision, and consistency checking.

Model catalog

Auto-generated model reference pages from AI Gateway with stable slugs.

Model pricing matrix

Compare input/output/image pricing across all discovered models, plus prompt-settlement notes for flat tool invocation billing.

Automation + Surveys

Configure managed automation and survey delivery workflows from first-party surfaces.

TypeScript SDK

Type-safe SDK with autocomplete support.

Python SDK

Idiomatic Python client for server-side apps.

R SDK

Researcher-friendly client for statistical workflows.

Concept reference

Deep, operational documentation for each core concept in the synthetic research workflow.

Persona

A durable synthetic individual

A persona is the identity anchor for all research interactions: stable profile, evolving memory, and consistent voice.

Open concept docs

Skill

A reusable research task

A skill defines what you ask and how you evaluate it, so prompt execution can be repeated across personas and studies.

Open concept docs

Cohort

A targeted segment within your audience

A cohort groups personas with shared attributes so you can reason about segment-specific behavior before scaling to full populations.

Open concept docs

Population

A complete synthetic panel

A population combines cohorts into a balanced audience model you can run repeatable studies against at scale.

Open concept docs

Study

A controlled run across a population

A study binds a skill to a target population, runs at scale, and returns structured evidence for product decisions.

Open concept docs

REST API reference

Base URL: https://api.person.run · Authenticate with x-api-key: <key>

GET/personasList personas by tenant

POST/personasCreate persona from seed

GET/personas/:personaIdGet a single persona

PATCH/personas/:personaIdUpdate persona fields

DELETE/personas/:personaIdDelete a persona

GET/personas/:personaId/exportExport persona data

POST/personas/promptPrompt a persona (sync/async)

POST/personas/prompt/streamStream persona response (SSE)

GET/personas/prompt/jobs/:jobIdPoll async job status

GET/personas/prompt/sessionsList recent prompt sessions

GET/personas/:personaId/timelineGet persona timeline

POST/personas/:personaId/timelineAppend timeline memory

POST/personas/:personaId/timeline/:timelineId/supersedeSupersede a timeline entry

GET/personas/:personaId/consistencyRun consistency check

GET/personas/safety-policyGet tenant safety policy

PUT/personas/safety-policyUpsert safety policy

DELETE/personas/safety-policy/:tenantIdRemove safety policy

GET/skillsList skill definitions

POST/skillsCreate a skill definition

GET/tasksList task executions

GET/tasks/:taskIdGet task execution detail

PATCH/tasks/:taskId/controlPause/resume/cancel task execution

POST/tasks/:taskId/executeQueue task execution

GET/schedulesList schedules

POST/schedulesCreate one-time or recurring schedule

POST/schedules/:scheduleId/trigger-nowTrigger schedule immediately

GET/studiesList studies

POST/studiesCreate a study

POST/studies/:studyId/runsStart a study run

GET/healthHealth check with dependency status

GET/openapi.jsonOpenAPI specification

SDKs

REST API

stable

# No installation needed — use any HTTP client
curl https://api.person.run/health

OpenAPI Spec

stable

# Import into Postman, Insomnia, or any OpenAPI tool
curl https://api.person.run/openapi.json

TypeScript SDK

stable

npm install @person.run/sdkDownload .zip

Python SDK

stable

pip install person-sdkDownload .zip

R SDK

stable

devtools::install_github("person-run/person.run",
  subdir = "packages/sdk-r")

Download .zip