Agents
List agents
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Query Parameters
Items per page (cursor mode)
30int64value <= 100Pagination cursor (base64)
Free-text search filter
Filter by project UUID
Set to 'true' to include total_count (expensive)
Items per page (legacy offset mode)
50int64value <= 100Offset for legacy pagination
int64Response Body
application/json
application/problem+json
curl -X GET "https://loading/api/v1/agents"{
"$schema": "/api/v1/schemas/PaginatedAgentsResponse.json",
"has_more": true,
"items": [
{
"agent_id": "string",
"created_at": "2019-08-24T14:15:22Z",
"instance_count": 0,
"is_active": true,
"last_seen_at": "2019-08-24T14:15:22Z",
"mcp_enabled": [
"string"
],
"name": "string",
"owner_display_name": "string",
"owner_email": "string",
"owner_user_id": "string",
"project_id": "string",
"tenant_id": "string"
}
],
"next_cursor": "string",
"total_count": 0
}{
"$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"
}Create or update an agent
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
curl -X POST "https://loading/api/v1/agents" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{
"$schema": "/api/v1/schemas/AgentDetailResponse.json",
"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": "2019-08-24T14:15:22Z",
"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
},
"gender": "string",
"instance_count": 0,
"is_active": true,
"last_seen_at": "2019-08-24T14:15:22Z",
"mcp_enabled": [
"string"
],
"name": "string",
"owner_display_name": "string",
"owner_email": "string",
"owner_user_id": "string",
"personality_prompt": "string",
"preferences": {
"conversation_pace": "string",
"emotional_expression": "string",
"formality": "string",
"humor_style": "string"
},
"primary_traits": [
"string"
],
"project_id": "string",
"speech_patterns": [
"string"
],
"tenant_id": "string",
"true_dislikes": [
"string"
],
"true_interests": [
"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 a single agent by ID
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
Agent UUID or URL-encoded agent name (resolved against the caller's tenant)
Response Body
application/json
application/problem+json
curl -X GET "https://loading/api/v1/agents/string"{
"$schema": "/api/v1/schemas/AgentDetailResponse.json",
"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": "2019-08-24T14:15:22Z",
"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
},
"gender": "string",
"instance_count": 0,
"is_active": true,
"last_seen_at": "2019-08-24T14:15:22Z",
"mcp_enabled": [
"string"
],
"name": "string",
"owner_display_name": "string",
"owner_email": "string",
"owner_user_id": "string",
"personality_prompt": "string",
"preferences": {
"conversation_pace": "string",
"emotional_expression": "string",
"formality": "string",
"humor_style": "string"
},
"primary_traits": [
"string"
],
"project_id": "string",
"speech_patterns": [
"string"
],
"tenant_id": "string",
"true_dislikes": [
"string"
],
"true_interests": [
"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"
}Delete an agent and all data
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
Agent UUID or URL-encoded agent name
Response Body
application/json
application/problem+json
curl -X DELETE "https://loading/api/v1/agents/string"{
"$schema": "/api/v1/schemas/DeleteAgentOutputBody.json",
"deleted": {
"property1": 0,
"property2": 0
},
"errors": [
"string"
],
"status": "string",
"success": true
}{
"$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 agent capabilities
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
Agent UUID or URL-encoded agent name
Response Body
application/json
application/problem+json
curl -X GET "https://loading/api/v1/agents/string/capabilities"{
"$schema": "/api/v1/schemas/AgentCapabilities.json",
"autoLearnSkills": true,
"composio": true,
"customTools": [
{
"$schema": "/api/v1/schemas/CustomToolDefinition.json",
"description": "string",
"name": "string",
"parameters": null
}
],
"imageGeneration": true,
"imageUnlockedAt": "2019-08-24T14:15:22Z",
"inventory": true,
"knowledgeBase": true,
"knowledgeBaseProjectId": "string",
"knowledgeBaseScopeMode": "string",
"mcp_enabled": [
"string"
],
"memoryMode": "string",
"musicGeneration": true,
"musicUnlockedAt": "2019-08-24T14:15:22Z",
"pendingCapabilities": [
{
"capability": "string",
"context": "string"
}
],
"rememberName": true,
"skills": true,
"videoGeneration": true,
"videoUnlockedAt": "2019-08-24T14:15:22Z",
"voiceGeneration": true,
"voiceId": "string",
"voiceTier": 0,
"voiceUnlockedAt": "2019-08-24T14:15:22Z",
"webSearch": true,
"wisdom": true,
"wisdomPublicSharing": true
}{
"$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"
}Update agent capabilities
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
Agent UUID or URL-encoded agent name
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
curl -X PUT "https://loading/api/v1/agents/string/capabilities" \ -H "Content-Type: application/json" \ -d '{}'{
"$schema": "/api/v1/schemas/AgentCapabilities.json",
"autoLearnSkills": true,
"composio": true,
"customTools": [
{
"$schema": "/api/v1/schemas/CustomToolDefinition.json",
"description": "string",
"name": "string",
"parameters": null
}
],
"imageGeneration": true,
"imageUnlockedAt": "2019-08-24T14:15:22Z",
"inventory": true,
"knowledgeBase": true,
"knowledgeBaseProjectId": "string",
"knowledgeBaseScopeMode": "string",
"mcp_enabled": [
"string"
],
"memoryMode": "string",
"musicGeneration": true,
"musicUnlockedAt": "2019-08-24T14:15:22Z",
"pendingCapabilities": [
{
"capability": "string",
"context": "string"
}
],
"rememberName": true,
"skills": true,
"videoGeneration": true,
"videoUnlockedAt": "2019-08-24T14:15:22Z",
"voiceGeneration": true,
"voiceId": "string",
"voiceTier": 0,
"voiceUnlockedAt": "2019-08-24T14:15:22Z",
"webSearch": true,
"wisdom": true,
"wisdomPublicSharing": true
}{
"$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"
}Preview the resolved post-processing model for this agent
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
Agent UUID or URL-encoded agent name
Query Parameters
The chat model whose post-processing routing should be previewed
Response Body
application/json
application/problem+json
curl -X GET "https://loading/api/v1/agents/string/effective-post-processing-model?chat_model=string"{
"$schema": "/api/v1/schemas/EffectivePostProcessingModelOutputBody.json",
"max_tokens": 0,
"model": "string",
"provider": "string",
"temperature": 0.1
}{
"$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"
}Fork (clone) an agent
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
Source agent UUID or URL-encoded agent name
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Display name for the forked agent
Response Body
application/json
application/problem+json
curl -X POST "https://loading/api/v1/agents/string/fork" \ -H "Content-Type: application/json" \ -d '{}'{
"$schema": "/api/v1/schemas/ForkResponse.json",
"agent_id": "string",
"name": "string",
"source_agent_id": "string",
"status": "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 fork operation status
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
Forked agent UUID
Response Body
application/json
application/problem+json
curl -X GET "https://loading/api/v1/agents/string/fork/status"{
"$schema": "/api/v1/schemas/ForkStatusResponse.json",
"completed_at": "2019-08-24T14:15:22Z",
"error_message": "string",
"source_agent_id": "string",
"started_at": "2019-08-24T14:15:22Z",
"status": "string",
"tables_copied": 0,
"tables_total": 0
}{
"$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"
}Set or clear agent-scope post-processing model override
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
Agent UUID or URL-encoded agent name
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
curl -X PATCH "https://loading/api/v1/agents/string/post-processing-model" \ -H "Content-Type: application/json" \ -d '{}'{
"$schema": "/api/v1/schemas/UpdateAgentPostProcessingModelOutputBody.json",
"post_processing_model": "string",
"post_processing_provider": "string",
"success": true
}{
"$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"
}Update agent profile fields
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
Agent UUID or URL-encoded agent name
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
curl -X PATCH "https://loading/api/v1/agents/string/profile" \ -H "Content-Type: application/json" \ -d '{}'{
"$schema": "/api/v1/schemas/UpdateAgentProfileOutputBody.json",
"success": true
}{
"$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"
}Assign an agent to a different project
Authorization
bearerClerk Clerk session JWT from an authenticated dashboard user. Format: Bearer eyJ....
In: header
Path Parameters
Agent UUID or URL-encoded agent name
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
curl -X PATCH "https://loading/api/v1/agents/string/project" \ -H "Content-Type: application/json" \ -d '{ "project_id": "string" }'{
"$schema": "/api/v1/schemas/UpdateAgentProjectOutputBody.json",
"success": true
}{
"$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"
}Activate or deactivate an agent
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
Agent UUID or URL-encoded agent name
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Whether the agent should be active
Response Body
application/json
application/problem+json
curl -X PATCH "https://loading/api/v1/agents/string/status" \ -H "Content-Type: application/json" \ -d '{ "is_active": true }'{
"$schema": "/api/v1/schemas/SetAgentStatusOutputBody.json",
"agent_id": "string",
"is_active": true,
"success": true
}{
"$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 custom tools
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
Agent UUID or URL-encoded agent name
Response Body
application/json
application/problem+json
curl -X GET "https://loading/api/v1/agents/string/tools"{
"$schema": "/api/v1/schemas/ListCustomToolsOutputBody.json",
"tools": [
{
"$schema": "/api/v1/schemas/CustomToolDefinition.json",
"description": "string",
"name": "string",
"parameters": null
}
]
}{
"$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"
}Create a custom tool
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
Agent UUID or URL-encoded agent name
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
curl -X POST "https://loading/api/v1/agents/string/tools" \ -H "Content-Type: application/json" \ -d '{ "description": "string", "name": "string" }'{
"$schema": "/api/v1/schemas/CustomToolDefinition.json",
"description": "string",
"name": "string",
"parameters": null
}{
"$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"
}Delete a custom tool
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
Agent UUID or URL-encoded agent name
Tool name to delete
Response Body
application/json
application/problem+json
curl -X DELETE "https://loading/api/v1/agents/string/tools/string"{
"$schema": "/api/v1/schemas/DeleteCustomToolOutputBody.json",
"success": true
}{
"$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"
}Update a custom tool
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
Agent UUID or URL-encoded agent name
Tool name to update
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
curl -X PUT "https://loading/api/v1/agents/string/tools/string" \ -H "Content-Type: application/json" \ -d '{}'{
"$schema": "/api/v1/schemas/UpdateCustomToolOutputBody.json",
"success": true
}{
"$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"
}