Api
Insights
Get recent personality shifts
AuthorizationBearer <token>
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
agentId*string
Agent UUID or URL-encoded agent name
Response Body
application/json
application/problem+json
curl -X GET "https://loading/api/v1/agents/string/personality/recent-shifts"{
"$schema": "/api/v1/schemas/RecentShiftsResponse.json",
"shifts": [
{
"direction": "string",
"magnitude": "string",
"reasoning": "string",
"timeframe_days": 0,
"timestamp": "string",
"trait_name": "string",
"trigger_types": [
"string"
]
}
]
}{
"$schema": "/api/v1/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}Get significant personality moments
AuthorizationBearer <token>
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
agentId*string
Agent UUID or URL-encoded agent name
Query Parameters
limit?integer
Max moments to return (1-100)
Default
20Format
int64Response Body
application/json
application/problem+json
curl -X GET "https://loading/api/v1/agents/string/personality/significant-moments"{
"$schema": "/api/v1/schemas/SignificantMomentsResponse.json",
"moments": [
{
"created_at": "string",
"description": "string",
"emotional_impact": "string",
"location": "string",
"partner_name": "string",
"reasoning": "string",
"traits_affected": [
"string"
],
"trigger_type": "string"
}
]
}{
"$schema": "/api/v1/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}List per-user personality overlays
AuthorizationBearer <token>
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
agentId*string
Agent UUID or URL-encoded agent name
Response Body
application/json
application/problem+json
curl -X GET "https://loading/api/v1/agents/string/personality/users"{
"$schema": "/api/v1/schemas/UserOverlaysListResponse.json",
"overlays": [
{
"agent_id": "string",
"behaviors": {
"conflict_approach": "string",
"empathy_style": "string",
"question_frequency": "string",
"response_length": "string"
},
"big5": {
"agreeableness": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"conscientiousness": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"extraversion": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"neuroticism": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"openness": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
}
},
"created_at": "string",
"dimensions": {
"aesthetic": 0.1,
"assertiveness": 0.1,
"compassion": 0.1,
"enthusiasm": 0.1,
"industriousness": 0.1,
"intellect": 0.1,
"orderliness": 0.1,
"politeness": 0.1,
"volatility": 0.1,
"withdrawal": 0.1
},
"preferences": {
"conversation_pace": "string",
"emotional_expression": "string",
"formality": "string",
"humor_style": "string"
},
"primary_traits": [
"string"
],
"updated_at": "string",
"user_id": "string"
}
]
}{
"$schema": "/api/v1/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}Get user personality overlay
AuthorizationBearer <token>
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
agentId*string
Agent UUID or URL-encoded agent name
userId*string
User ID
Query Parameters
instance_id?string
Optional instance ID (scoped with userId)
since?string
Start date for evolution history (YYYY-MM-DD)
Response Body
application/json
application/problem+json
curl -X GET "https://loading/api/v1/agents/string/personality/users/string"{
"$schema": "/api/v1/schemas/UserOverlayDetailResponse.json",
"base": {
"agent_id": "string",
"avatar_url": "string",
"behaviors": {
"conflict_approach": "string",
"empathy_style": "string",
"question_frequency": "string",
"response_length": "string"
},
"big5": {
"agreeableness": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"conscientiousness": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"extraversion": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"neuroticism": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"openness": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
}
},
"bio": "string",
"created_at": "string",
"dimensions": {
"aesthetic": 0.1,
"assertiveness": 0.1,
"compassion": 0.1,
"enthusiasm": 0.1,
"industriousness": 0.1,
"intellect": 0.1,
"orderliness": 0.1,
"politeness": 0.1,
"volatility": 0.1,
"withdrawal": 0.1
},
"emotional_tendencies": {
"property1": 0.1,
"property2": 0.1
},
"gender": "string",
"name": "string",
"personality_prompt": "string",
"preferences": {
"conversation_pace": "string",
"emotional_expression": "string",
"formality": "string",
"humor_style": "string"
},
"primary_traits": [
"string"
],
"speech_patterns": [
"string"
],
"temperature": 0.1,
"trait_precisions": {
"property1": {
"last_updated_at": "2019-08-24T14:15:22Z",
"observation_count": 0,
"precision": 0.1
},
"property2": {
"last_updated_at": "2019-08-24T14:15:22Z",
"observation_count": 0,
"precision": 0.1
}
},
"true_dislikes": [
"string"
],
"true_interests": [
"string"
]
},
"evolution": [
{
"applied_delta": 0.1,
"confidence": 0.1,
"dampening_factor": 0.1,
"delta": 0.1,
"is_significant_moment": true,
"new_value": 0.1,
"old_value": 0.1,
"posterior_precision": 0.1,
"prediction_error": 0.1,
"prior_precision": 0.1,
"proposed_delta": 0.1,
"reasoning": "string",
"timestamp": "2019-08-24T14:15:22Z",
"trait_category": "string",
"trait_name": "string",
"trigger_type": "string",
"user_id": "string"
}
],
"overlay": {
"agent_id": "string",
"behaviors": {
"conflict_approach": "string",
"empathy_style": "string",
"question_frequency": "string",
"response_length": "string"
},
"big5": {
"agreeableness": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"conscientiousness": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"extraversion": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"neuroticism": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"openness": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
}
},
"created_at": "string",
"dimensions": {
"aesthetic": 0.1,
"assertiveness": 0.1,
"compassion": 0.1,
"enthusiasm": 0.1,
"industriousness": 0.1,
"intellect": 0.1,
"orderliness": 0.1,
"politeness": 0.1,
"volatility": 0.1,
"withdrawal": 0.1
},
"preferences": {
"conversation_pace": "string",
"emotional_expression": "string",
"formality": "string",
"humor_style": "string"
},
"primary_traits": [
"string"
],
"updated_at": "string",
"user_id": "string"
}
}{
"$schema": "/api/v1/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}Reconstruct personality at a point in time
AuthorizationBearer <token>
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
agentId*string
Agent UUID or URL-encoded agent name
Query Parameters
at*string
ISO 8601 timestamp to reconstruct personality at
Response Body
application/json
application/problem+json
curl -X GET "https://loading/api/v1/agents/string/timemachine?at=2025-06-15T12%3A00%3A00Z"{
"$schema": "/api/v1/schemas/TimeMachineResponse.json",
"current_personality": {
"agreeableness": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"conscientiousness": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"extraversion": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"neuroticism": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"openness": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
}
},
"evolution_events": [
{
"applied_delta": 0.1,
"confidence": 0.1,
"dampening_factor": 0.1,
"delta": 0.1,
"is_significant_moment": true,
"new_value": 0.1,
"old_value": 0.1,
"posterior_precision": 0.1,
"prediction_error": 0.1,
"prior_precision": 0.1,
"proposed_delta": 0.1,
"reasoning": "string",
"timestamp": "2019-08-24T14:15:22Z",
"trait_category": "string",
"trait_name": "string",
"trigger_type": "string",
"user_id": "string"
}
],
"mood_at": {
"affiliation": 0.1,
"arousal": 0.1,
"label": "string",
"tension": 0.1,
"valence": 0.1
},
"personality_at": {
"agreeableness": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"conscientiousness": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"extraversion": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"neuroticism": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
},
"openness": {
"confidence": 0.1,
"facets": [
"string"
],
"level": "string",
"score": 0.1
}
},
"requested_at": "string"
}{
"$schema": "/api/v1/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}