Built in Agents
List Sonzai built-in backend agents
AuthorizationBearer <token>
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Response Body
application/json
application/problem+json
curl -X GET "https://loading/api/v1/builtin-agents"{
"$schema": "/api/v1/schemas/ListBuiltinAgentsResponse.json",
"agents": [
{
"description": "string",
"model": "string",
"name": "string",
"provisioned": true,
"slug": "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 built-in agent chat sessions
AuthorizationBearer <token>
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Query Parameters
limit?integer
Default
50Format
int64Response Body
application/json
application/problem+json
curl -X GET "https://loading/api/v1/builtin-agents/sessions"{
"$schema": "/api/v1/schemas/ListBuiltinAgentSessionsResponse.json",
"sessions": [
{
"$schema": "/api/v1/schemas/SessionBody.json",
"agent": "string",
"byok": true,
"cost_usd": 0.1,
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"model": "string",
"status": "string",
"title": "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"
}Start a chat session with a built-in agent
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/builtin-agents/sessions" \ -H "Content-Type: application/json" \ -d '{ "agent": "string" }'{
"$schema": "/api/v1/schemas/SessionBody.json",
"agent": "string",
"byok": true,
"cost_usd": 0.1,
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"model": "string",
"status": "string",
"title": "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 built-in agent session (status, billed usage, cost)
AuthorizationBearer <token>
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
id*string
Response Body
application/json
application/problem+json
curl -X GET "https://loading/api/v1/builtin-agents/sessions/string"{
"$schema": "/api/v1/schemas/GetBuiltinAgentSessionResponse.json",
"billed_cache_creation_tokens": 0,
"billed_cache_read_tokens": 0,
"billed_input_tokens": 0,
"billed_output_tokens": 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"
}Send a chat message to a built-in agent session
AuthorizationBearer <token>
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
id*string
Query Parameters
stream?boolean
true → SSE of live agent events ending in a final result event
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/problem+json
curl -X POST "https://loading/api/v1/builtin-agents/sessions/string/messages" \ -H "Content-Type: application/json" \ -d '{ "text": "string" }'Empty
{
"$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"
}Run a built-in agent task
AuthorizationBearer <token>
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
slug*string
Built-in agent slug, e.g. lead_research
Query Parameters
stream?boolean
true → stream live agent progress as SSE; false → block and return JSON
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/problem+json
curl -X POST "https://loading/api/v1/builtin-agents/string/invoke" \ -H "Content-Type: application/json" \ -d '{ "input": { "property1": null, "property2": null } }'Empty
{
"$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"
}