Code Examples
Ready-to-use examples for interacting with the Ensoul API. All examples use the REST API directly with cURL and JavaScript fetch — no SDK required.
💡
Use an SDK
These examples use the REST API directly. For a simpler experience, use one of our official SDKs — available for Python, TypeScript, Kotlin, Swift, Unity, C++, and Godot.
List Domains
Retrieve all domains accessible to your account.
curl -X GET "https://api.ensoul-ai.com/v1/domains" \
-H "X-API-Key: YOUR_API_KEY"List Personas
List personas with pagination and optional filters (region, archetype, country, city). Results come back in a paginated envelope.
curl -X GET "https://api.ensoul-ai.com/v1/personas?page=1&per_page=20" \
-H "X-API-Key: YOUR_API_KEY"Chat with a Persona
Send a message to a persona and receive their response. Every response is generated through real-time inference.
curl -X POST "https://api.ensoul-ai.com/v1/personas/PERSONA_UUID/chat" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "What do you think about remote work?"
}'Example Response
json
{"response": "Honestly, I've really grown to appreciate remote work. The flexibility has been amazing for my productivity...","conversation_id": "conversation-uuid","latency_ms": 842,"model": "claude-sonnet-4-6","timestamp": "2026-01-15T10:40:00Z"}
Run an Aggregate Query
Query multiple personas at once for population-level insights. Results are streamed as server-sent events.
curl -X POST "https://api.ensoul-ai.com/v1/aggregate/stream" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domain_id": "DOMAIN_UUID",
"question": "What are your thoughts on work-life balance?",
"sample_size": 10
}'Create a Persona
Create a new persona in a domain, optionally specifying an archetype to base it on.
curl -X POST "https://api.ensoul-ai.com/v1/personas" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Maya Okonkwo",
"domain": "your-domain",
"archetype": "archetype-id"
}'Error Handling
All examples should include proper error handling:
javascript
async function apiCall(path, options = {}) {const response = await fetch(path, {...options,headers: {"X-API-Key": API_KEY,"Content-Type": "application/json",...options.headers}});if (!response.ok) {const error = await response.json().catch(() => ({}));if (response.status === 401) {throw new Error("Invalid API key");} else if (response.status === 429) {throw new Error("Rate limited - wait before retrying");} else {throw new Error(error.message || `HTTP ${response.status}`);}}return response.json();}