Skip to main content
SONZAI
Api

Agents

List agents

GET
/agents
AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Query Parameters

page_size?integer

Items per page (cursor mode)

Default30
Formatint64
Rangevalue <= 100
cursor?string

Pagination cursor (base64)

search?string

Free-text search filter

project_id?string

Filter by project UUID

include_count?string

Set to 'true' to include total_count (expensive)

limit?integer

Items per page (legacy offset mode)

Default50
Formatint64
Rangevalue <= 100
offset?integer

Offset for legacy pagination

Formatint64

Response 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

POST
/agents
AuthorizationBearer <token>

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

GET
/agents/{agentId}
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 (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

DELETE
/agents/{agentId}
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 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

GET
/agents/{agentId}/capabilities
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/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

PUT
/agents/{agentId}/capabilities
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

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

GET
/agents/{agentId}/effective-post-processing-model
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

chat_model*string

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

POST
/agents/{agentId}/fork
AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

agentId*string

Source agent UUID or URL-encoded agent name

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

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

GET
/agents/{agentId}/fork/status
AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

agentId*string

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

PATCH
/agents/{agentId}/post-processing-model
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

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

PATCH
/agents/{agentId}/profile
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

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

PATCH
/agents/{agentId}/project

Authorization

bearerClerk
AuthorizationBearer <token>

Clerk session JWT from an authenticated dashboard user. Format: Bearer eyJ....

In: header

Path Parameters

agentId*string

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

PATCH
/agents/{agentId}/status
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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

is_active*boolean

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

GET
/agents/{agentId}/tools
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/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

POST
/agents/{agentId}/tools
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

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

DELETE
/agents/{agentId}/tools/{toolName}
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

toolName*string

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

PUT
/agents/{agentId}/tools/{toolName}
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

toolName*string

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"
}