API Reference

The Ensoul API provides programmatic access to create domains, generate personas, conduct conversations, run aggregate queries, and manage simulations.

API access requires authentication via API key or OAuth. See the SDKs page for official client libraries.

The hosted API base URL is https://api.ensoul-ai.com. All endpoint paths below are versioned under /v1 (for example, https://api.ensoul-ai.com/v1/domains).

Authentication

Ensoul supports two authentication methods:

Google OAuth (UI)

For browser-based access through Ensoul Studio. Authentication is handled automatically via session cookies after Google sign-in.

API Keys (Programmatic)

For server-to-server communication. API keys are created in the Studio UI under Settings → API Keys and belong to your team.

Using API Keys

Pass your API key in the X-API-Key header (OAuth users send a JWT in the Authorization: Bearer header instead):

bash

curl -X GET "https://api.ensoul-ai.com/v1/domains" \
  -H "X-API-Key: your_api_key_here"

⚠

Security

Never expose API keys in client-side code. Revoke and rotate keys anytime in Settings → API Keys.

Domains

Manage personality domains — the foundation for all persona generation.

GET/v1/domains

List all domains accessible to your account.

POST/v1/domains

Create a new domain (use Studio wizard for guided creation).

GET/v1/domains/:id

Get a specific domain by ID with full configuration.

POST/v1/domains/generate

AI-generate a complete domain from a text description.

Personas

Generate and manage personas within a domain.

GET/v1/personas

List personas with pagination and filters (region, archetype, country, city).

POST/v1/personas

Create a persona (pass the target domain in the request body).

POST/v1/personas/batch

Create multiple personas at once with controlled distribution.

GET/v1/personas/:id

Get a specific persona with full trait profile.

GET/v1/personas/:id/personality

Get a persona's full personality vector.

Chat

1:1 conversations with individual personas. Every response is generated through real-time inference.

POST/v1/personas/:id/chat

Send a message to a persona and receive a response.

Request Body

json

{
  "message": "What do you think about remote work?",
  "conversation_id": "optional-conversation-uuid"
}

POST/v1/personas/:id/chat/stream

Stream a persona's response token-by-token via Server-Sent Events.

GET/v1/chat/sessions

List chat sessions.

GET/v1/chat/sessions/:id

Get a specific chat session with message history.

Aggregate Queries

Query multiple personas at once for population-level insights.

POST/v1/aggregate/stream

Stream aggregate query results across multiple personas.

POST/v1/aggregate/stream/grouped

Stream grouped aggregate results (by archetype or tier).

GET/v1/aggregate/count

Get the count of personas matching query filters.

Simulations

Run multi-step simulations where personas interact and evolve over time.

GET/v1/simulations

List all simulations.

POST/v1/simulations

Create a new simulation.

GET/v1/simulations/:id

Get simulation details and status.

POST/v1/simulations/:id/start

Start a simulation.

POST/v1/simulations/:id/pause

Pause a running simulation.

PATCH/v1/simulations/:id/speed

Adjust simulation speed.

GET/v1/simulations/:id/stream

Stream real-time simulation events (SSE).

GET/v1/simulations/:id/history

Get simulation interaction history.

GET/v1/simulations/:id/checkpoints

List simulation checkpoints.

POST/v1/simulations/:id/checkpoints/:cpId/restore

Restore simulation to a checkpoint.

Persona Memories

Manage persona long-term memories and batch memory generation.

GET/v1/memory/:personaId

List memories for a persona.

POST/v1/memory/:personaId/generate

Generate memories for a persona (using bloom modes).

POST/v1/memory/:personaId/batch

Batch create memories.

DELETE/v1/memory/:personaId/:memoryId

Delete a specific memory.

POST/v1/domains/:id/memories/generate-batch

Batch generate memories for all personas in a domain.

GET/v1/domains/:id/memories/bloom-jobs

List bloom (memory generation) jobs.

POST/v1/domains/:id/memories/bloom-jobs/:jobId/cancel

Cancel a running bloom job.

Frameworks & Validation

Manage personality frameworks and run validation experiments.

GET/v1/frameworks

List available personality frameworks.

GET/v1/frameworks/:id

Get framework details including traits and grounding.

GET/v1/frameworks/:id/traits/:traitName/grounding

Get/update trait grounding text.

POST/v1/frameworks/:id/auto-tune

AI-generate improved trait grounding.

GET/v1/validations

List validation runs.

POST/v1/validations

Start a new validation experiment.

GET/v1/validations/:id

Get validation results.

GET/v1/validations/:id/tuning-report

Get auto-tune report for a validation.

Error Handling

The API uses standard HTTP status codes and returns detailed error information:

json

{
  "error": "Validation Error",
  "message": "Request validation failed",
  "details": [
    { "field": "message", "message": "field required", "type": "missing" }
  ],
  "request_id": "req_a1b2c3d4"
}

Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request — Invalid parameters
401	Unauthorized — Invalid or missing credentials
403	Forbidden — Insufficient permissions
404	Not Found — Resource doesn't exist
429	Rate Limited — Too many requests
500	Server Error — Something went wrong

Rate Limits

Rate limits depend on your plan:

Plan	Requests/min	Personas/month
Free Demo	10	100
Custom (contact us)	Higher	Up to unlimited

Next Steps

SDKs

Official client libraries for 7 languages

Quickstart Guide

Get started with Ensoul Studio

Code Examples

Copy-paste cURL and JavaScript examples

Domain Architecture

Create custom personality domains