Skip to main content

API Reference

Self-Model API

Explore the endpoints that power compounding user understanding. Browse request/response examples, copy cURL commands, and see the data structures behind self-models.

Download OpenAPI Spec v1.0.0 · 130 endpoints
POST/external/onboarding
POST/external/onboarding201

Register External User

Requires X-API-Key
Request Body
{
  "email": "string",
  "external_id": {},
  "app_id": {},
  "metadata": {}
}
Response · 201
{
  "user_id": "abc123",
  "external_id": {},
  "email": "string",
  "created": true,
  "self_model_id": {}
}
cURL
curl -X POST \
  https://api.heyclarity.dev/external/onboarding \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"string","external_id":{},"app_id":{},"metadata":{}}'
GET/external/onboarding
GET/external/onboarding200

Get External User

Requires X-API-Key
Query Parameters
NameTypeRequiredDescription
user_idstringoptionalInternal user ID
external_idstringoptionalExternal system user ID
Response · 200
{
  "user_id": "abc123",
  "external_id": {},
  "email": "string",
  "created": true,
  "self_model_id": {}
}
cURL
curl -X GET \
  https://api.heyclarity.dev/external/onboarding \
  -H "X-API-Key: YOUR_API_KEY"
POST/external/input
POST/external/input200

Process Input

Requires X-API-Key
Request Body
{
  "envelope_id": "abc123",
  "user_id": "abc123",
  "input_type": "string",
  "schema_version": "1.0",
  "timestamp": "string",
  "data": {},
  "session_id": {},
  "customer_journey_stage": {}
}
Response · 200
{}
cURL
curl -X POST \
  https://api.heyclarity.dev/external/input \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"envelope_id":"abc123","user_id":"abc123","input_type":"string","schema_version":"1.0","timestamp":"string","data":{},"session_id":{},"customer_journey_stage":{}}'
GET/external/input/{envelope_id}/status
GET/external/input/{envelope_id}/status200

Get Envelope Status

Requires X-API-Key
Response · 200
{
  "envelope_id": "abc123",
  "status": "string",
  "episode_id": {},
  "belief_ids": [
    1
  ],
  "error_message": {}
}
cURL
curl -X GET \
  https://api.heyclarity.dev/external/input/{envelope_id}/status \
  -H "X-API-Key: YOUR_API_KEY"
POST/external/sessions
POST/external/sessions200

Create Session

Requires X-API-Key
Request Body
{
  "user_id": "abc123",
  "session_type": "onboarding",
  "expected_episode_count": 1,
  "metadata": {},
  "causation_id": {},
  "correlation_id": {}
}
Response · 200
{
  "session_id": "abc123",
  "status": "created"
}
cURL
curl -X POST \
  https://api.heyclarity.dev/external/sessions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"abc123","session_type":"onboarding","expected_episode_count":1,"metadata":{},"causation_id":{},"correlation_id":{}}'
GET/external/sessions/{session_id}
GET/external/sessions/{session_id}200

Get Session

Requires X-API-Key
Response · 200
{
  "session_id": "abc123",
  "user_id": "abc123",
  "session_type": "string",
  "expected_episode_count": 1,
  "processed_episode_count": 1,
  "status": "string",
  "metadata": {},
  "self_model_snapshot": {}
}
cURL
curl -X GET \
  https://api.heyclarity.dev/external/sessions/{session_id} \
  -H "X-API-Key: YOUR_API_KEY"
POST/external/sessions/{session_id}/fail
POST/external/sessions/{session_id}/fail200

Mark Session Failed

Requires X-API-Key
Request Body
{
  "error_message": "string"
}
Response · 200
{}
cURL
curl -X POST \
  https://api.heyclarity.dev/external/sessions/{session_id}/fail \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"error_message":"string"}'
POST/external/sessions/cleanup
POST/external/sessions/cleanup200

Cleanup Stale Sessions

Requires X-API-Key
Request Body
{
  "timeout_minutes": 60
}
Response · 200
{
  "abandoned_count": 1,
  "timeout_minutes": 1
}
cURL
curl -X POST \
  https://api.heyclarity.dev/external/sessions/cleanup \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeout_minutes":60}'
POST/external/context
POST/external/context200

Assemble Context

Requires X-API-Key
Query Parameters
NameTypeRequiredDescription
requesting_user_idstringrequiredUser ID for authorization
Request Body
{
  "self_model_id": {},
  "user_id": {},
  "view_id": {},
  "app_id": {},
  "format": "ai_ready",
  "include_beliefs": true,
  "include_narrative": true,
  "include_recommendations": true
}
Response · 200
{
  "context_id": "abc123",
  "format": "ai_ready",
  "computed_at": "2026-03-18T00:00:00Z",
  "ai_ready": {},
  "raw": {},
  "summary": {},
  "self_model_id": 1,
  "user_id": "abc123"
}
cURL
curl -X POST \
  https://api.heyclarity.dev/external/context \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"self_model_id":{},"user_id":{},"view_id":{},"app_id":{},"format":"ai_ready","include_beliefs":true,"include_narrative":true,"include_recommendations":true}'
GET/external/context/formats
GET/external/context/formats200

List Context Formats

Requires X-API-Key
Response · 200
{
  "formats": [
    {
      "id": "abc123",
      "name": "string",
      "description": "string",
      "use_cases": [
        {}
      ]
    }
  ],
  "default_format": "ai_ready"
}
cURL
curl -X GET \
  https://api.heyclarity.dev/external/context/formats \
  -H "X-API-Key: YOUR_API_KEY"

Ready to build with self-models?

Get early access to the Clarity API — documentation, quickstart guides, and API keys.

Book a Strategy Call

We'll only email you about early access. No spam.