Developer Docs

Personality Intelligence API

Integrate deep psychological understanding into your application with a single API call. Every message builds a living personality profile.

Authentication

All API requests require an API key passed via the x-api-key header. The API key identifies your application and tracks usage against your profiled-user quota.

Getting Your API Key

Sign up and log in at profile-engine.com/login
Go to the dashboard and create an API key under the API Keys panel
Copy the key immediately — it is only shown once

bash

curl -X POST https://profile-engine.com/api/understand \
  -H "x-api-key: pe_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{"input": "I have been thinking about changing careers.", "type": "conversation"}'

NOTEAPI keys use the prefix pe_live_. Store them securely and never expose them in client-side code.

Endpoints

ProfileEngine exposes three core endpoints. The user identity is determined by your API key — each key is tied to your account.

Method	Endpoint	Purpose
POST	/api/understand	5-layer psychological analysis
POST	/api/converse	Conversation with context and response
GET	/api/profile	Retrieve the living profile

POST /api/understand

Send any input through the 5-layer analysis engine. Each call evolves the personality profile and returns deep psychological understanding.

Request

bash

curl -X POST https://profile-engine.com/api/understand \
  -H "x-api-key: pe_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "input": "I have been thinking about changing careers lately.",
    "type": "conversation"
  }'

Body Fields

input

requiredThe text to analyze (user message, journal entry, etc.)

type

Input type hint. Default: "unknown". Common values: "conversation", "journal", "reflection"

Response

json

{
  "understanding": {
    "surface": "Considering a career change",
    "emotional": "Restlessness mixed with fear of the unknown",
    "shadow": "Fear that staying means giving up on potential",
    "soul": "Deep desire for meaningful work aligned with identity",
    "growth_edge": "Ready to explore what 'meaningful' actually means",
    "key_insights": ["..."],
    "patterns_noticed": ["..."],
    "breakthrough_potential": 0.72
  },
  "profile_evolution": {
    "core_identity": { "essence": "...", "becoming": "..." },
    "current_edge": "...",
    "understanding_confidence": 0.65,
    "evolution_stage": "emerging"
  },
  "next_questions": ["..."],
  "timestamp": 1707849600000
}

Response Fields

understanding

5-layer analysis with surface, emotional, shadow, soul, and growth_edge insights plus key_insights, patterns_noticed, and breakthrough_potential (0-1).

profile_evolution

How the profile changed from this input. Includes core_identity, current growth edge, confidence score, and evolution_stage.

next_questions

AI-generated follow-up questions derived from patterns noticed.

POST /api/converse

Full conversation endpoint. Analyzes the message, evolves the profile, and generates an evidence-based response with MI and IFS analysis.

Request

bash

curl -X POST https://profile-engine.com/api/converse \
  -H "x-api-key: pe_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "I keep putting off the hard conversation with my manager.",
    "sessionId": "session_abc",
    "context_hint": "workplace"
  }'

Body Fields

message

requiredThe user message to process

sessionId

Session identifier for conversation continuity. Auto-generated if omitted.

context_hint

Optional hint about the conversation context (e.g. "workplace", "relationship")

Response

json

{
  "response": "AI-generated conversational response",
  "question": "Follow-up question to deepen understanding",
  "understanding_layers": {
    "surface": "...", "emotional": "...",
    "shadow": "...", "soul": "...", "growth_edge": "..."
  },
  "profile_summary": "You are ..., becoming ...",
  "breakthrough_potential": 0.68,
  "understanding_confidence": 0.72,
  "conversation_depth": 5,
  "depth_level": "moderate",
  "ready_for_deep_insights": true,
  "evidence_based_insight": "...",
  "mi_phase": "contemplation",
  "change_talk_ratio": 0.6,
  "readiness_level": "moderate",
  "ifs_dominant_part": "protector",
  "ifs_self_energy": 0.45,
  "timestamp": 1707849600000
}

GET /api/profile

Retrieve the living profile. The profile reflects the cumulative understanding built from all prior interactions. The user is identified by your API key.

bash

curl https://profile-engine.com/api/profile \
  -H "x-api-key: pe_live_a1b2c3d4..."

Response

json

{
  "profile": {
    "core_identity": { "essence": "...", "becoming": "..." },
    "patterns": [...],
    "shadows": [...],
    "gifts": [...],
    "growth": { "current_edge": "..." },
    "understanding_confidence": 0.87,
    "evolution_stage": "deepening"
  },
  "current_insights": {
    "essence_reflection": "...",
    "growth_invitation": "...",
    "breakthrough_potential": 0.75
  },
  "profile_summary": "You are ..., becoming ...",
  "timestamp": 1707849600000
}

Concepts

5-Layer Model

Surface→Emotional→Shadow→Soul→Growth Edge

Each message is analyzed across all five depths. Earlier layers capture what the user explicitly communicated. Deeper layers reveal underlying emotional patterns, hidden motivations, core identity, and areas where the user is ready to grow.

Big Five (OCEAN)

OpennessConscientiousnessExtraversionAgreeablenessNeuroticism

Personality traits are inferred from conversation with evidence citations rather than self-report questionnaires. Scores range from 0 to 1 and evolve over time as more interactions provide additional evidence.

Motivational Interviewing (MI)

PrecontemplationContemplationPreparationActionMaintenance

Detects which readiness stage a user is in regarding change or growth. The analysis identifies change talk (language indicating motivation to change) versus sustain talk (language indicating resistance to change).

Internal Family Systems (IFS)

ProtectorsExilesManagers

Identifies psychological parts from conversational patterns. Protectors guard against perceived threats, exiles hold painful emotions or memories, and managers maintain day-to-day functioning and control.

Rate Limits & Errors

There are no per-call rate limits. Pricing is based on profiled users, not API calls. Send as many messages as you need for each user.

Code	Meaning
400	Invalid request body or missing required fields
401	Missing or invalid API key
403	API key revoked or quota exceeded
500	Internal server error