Re-evaluate an existing transcript

Authorization

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.

adaptation_template_id?string

Optional adaptation-eval template UUID

quality_only?boolean

Skip adaptation evaluation

source_run_id*string

UUID of the existing run whose transcript is being re-evaluated

template_id*string

Quality-eval template UUID to apply

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/agents/string/eval-only" \  -H "Content-Type: application/json" \  -d '{    "source_run_id": "string",    "template_id": "string"  }'

{
  "$schema": "/api/v1/schemas/RunningBody.json",
  "run_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"
}

Evaluate an agent conversation

Authorization

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.

adaptation_template_id?string

Optional adaptation-eval template UUID; defaults to tenant's first adaptation template

config_override?

Override selected fields of the agent's character config for this run only

messages*array<>|

Transcript messages — at least 2 required

model?string

Override LLM model (judge model comes from the template)

provider?string

Override LLM provider for this run (e.g. gemini, openrouter). Accepted for forward-compat; currently unused server-side (judge provider comes from the template).

quality_only?boolean

Skip adaptation evaluation and only run quality scoring

simulation_config?unknown

Opaque simulator config to include on the run record

simulation_state?unknown

Opaque simulator state to include on the run record

template_id*string

Quality-eval template UUID

user_persona?unknown

Synthetic user persona used during the simulation

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/agents/string/evaluate" \  -H "Content-Type: application/json" \  -d '{    "messages": [      {        "content": "string",        "role": "string"      }    ],    "template_id": "string"  }'

{
  "$schema": "/api/v1/schemas/EvaluateAcceptedBody.json",
  "run_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"
}

Run simulation and evaluation

Authorization

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.

adaptation_template_id?string

Optional adaptation-eval template UUID; defaults to the tenant's first adaptation template

config_override?

Override selected fields of the agent's character config for this run

model?string

LLM model override

quality_only?boolean

Skip adaptation evaluation

sessions?array<>|

Session configurations driving the simulator

simulation_config?

Simulator configuration

template_id*string

Quality-eval template UUID

user_persona?

Synthetic user persona

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/agents/string/run-eval" \  -H "Content-Type: application/json" \  -d '{    "template_id": "string"  }'

{
  "$schema": "/api/v1/schemas/RunningBody.json",
  "run_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"
}

Run an agent simulation

Authorization

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.

config?

Simulator configuration (durations, proactivity, consolidation)

config_override?

Override selected fields of the agent's character config for this run

model?string

Agent LLM model override

sessions?array<>|

Session configurations driving the simulator

user_id?string

Stable user ID for CE memory scoping

user_persona?

Synthetic user persona (defaults to DefaultUserPersona)

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/agents/string/simulate" \  -H "Content-Type: application/json" \  -d '{}'

{
  "$schema": "/api/v1/schemas/SimulateRunningBody.json",
  "run_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"
}

List eval runs

Authorization

AuthorizationBearer <token>

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

In: header

Query Parameters

agent_id?string

Filter by agent ID

limit?integer

Items per page (default 20)

Default20

Formatint64

offset?integer

Pagination offset

Default0

Formatint64

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://loading/api/v1/eval-runs"

{
  "$schema": "/api/v1/schemas/ListEvalRunsOutputBody.json",
  "runs": [
    {
      "$schema": "/api/v1/schemas/EvalRun.json",
      "adaptation_result": null,
      "adaptation_template_id": "string",
      "adaptation_template_snapshot": null,
      "agent_id": "string",
      "agent_name": "string",
      "character_config": null,
      "completed_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "error_reason": "string",
      "evaluation_cost_usd": 0.1,
      "evaluation_result": null,
      "project_id": "string",
      "run_id": "string",
      "simulated_minutes": 0,
      "simulation_config": null,
      "simulation_cost_usd": 0.1,
      "simulation_model": "string",
      "simulation_state": null,
      "started_at": "2019-08-24T14:15:22Z",
      "status": "string",
      "template_id": "string",
      "template_snapshot": null,
      "tenant_id": "string",
      "total_cost_usd": 0.1,
      "total_sessions": 0,
      "total_turns": 0,
      "transcript": null,
      "user_persona": null
    }
  ],
  "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"
}

Get an eval run

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

runId*string

Eval run UUID

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://loading/api/v1/eval-runs/string"

{
  "$schema": "/api/v1/schemas/EvalRun.json",
  "adaptation_result": null,
  "adaptation_template_id": "string",
  "adaptation_template_snapshot": null,
  "agent_id": "string",
  "agent_name": "string",
  "character_config": null,
  "completed_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "error_reason": "string",
  "evaluation_cost_usd": 0.1,
  "evaluation_result": null,
  "project_id": "string",
  "run_id": "string",
  "simulated_minutes": 0,
  "simulation_config": null,
  "simulation_cost_usd": 0.1,
  "simulation_model": "string",
  "simulation_state": null,
  "started_at": "2019-08-24T14:15:22Z",
  "status": "string",
  "template_id": "string",
  "template_snapshot": null,
  "tenant_id": "string",
  "total_cost_usd": 0.1,
  "total_sessions": 0,
  "total_turns": 0,
  "transcript": null,
  "user_persona": 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 an eval run

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

runId*string

Eval run UUID

Response Body

`application/json`

`application/problem+json`

curl -X DELETE "https://loading/api/v1/eval-runs/string"

{
  "$schema": "/api/v1/schemas/DeleteEvalRunOutputBody.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"
}

Stream eval run events (SSE)

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

runId*string

Eval run UUID

Query Parameters

from?integer

Event index to stream from (default 0)

Default0

Formatint64

Response Body

`text/event-stream`

`application/problem+json`

curl -X GET "https://loading/api/v1/eval-runs/string/events"

{
  "$schema": "/api/v1/schemas/EvalRunEvent.json",
  "adaptation_result": null,
  "error_reason": "string",
  "evaluation_result": null,
  "status": "string",
  "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 eval templates

Authorization

AuthorizationBearer <token>

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

In: header

Query Parameters

type?string

Filter by template type (e.g. quality, adaptation)

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://loading/api/v1/eval-templates"

{
  "$schema": "/api/v1/schemas/ListEvalTemplatesOutputBody.json",
  "templates": [
    {
      "$schema": "/api/v1/schemas/EvalTemplate.json",
      "categories": [
        {
          "key": "string",
          "label": "string",
          "prompt_instructions": "string"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "description": "string",
      "is_system": true,
      "judge_model": "string",
      "max_tokens": 0,
      "name": "string",
      "scoring_rubric": "string",
      "temperature": 0.1,
      "template_id": "string",
      "template_type": "string",
      "tenant_id": "string",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

{
  "$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 an eval template

Authorization

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.

categories?array<>|

Evaluation categories

description?string

Template description

judge_model?string

Judge LLM model (default: gemini-3.1-pro-preview)

max_tokens?integer

Max tokens (default: 8192)

Formatint32

name*string

Template name

scoring_rubric?string

Scoring rubric prompt

temperature?number

Sampling temperature (default: 0.3)

Formatdouble

template_type?string

Template type (quality or adaptation)

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/eval-templates" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{
  "$schema": "/api/v1/schemas/EvalTemplate.json",
  "categories": [
    {
      "key": "string",
      "label": "string",
      "prompt_instructions": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "description": "string",
  "is_system": true,
  "judge_model": "string",
  "max_tokens": 0,
  "name": "string",
  "scoring_rubric": "string",
  "temperature": 0.1,
  "template_id": "string",
  "template_type": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "$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 an eval template

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

templateId*string

Template UUID

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://loading/api/v1/eval-templates/string"

{
  "$schema": "/api/v1/schemas/EvalTemplate.json",
  "categories": [
    {
      "key": "string",
      "label": "string",
      "prompt_instructions": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "description": "string",
  "is_system": true,
  "judge_model": "string",
  "max_tokens": 0,
  "name": "string",
  "scoring_rubric": "string",
  "temperature": 0.1,
  "template_id": "string",
  "template_type": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "$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 eval template

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

templateId*string

Template UUID

Response Body

`application/json`

`application/problem+json`

curl -X DELETE "https://loading/api/v1/eval-templates/string"

{
  "$schema": "/api/v1/schemas/DeleteEvalTemplateOutputBody.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 an eval template

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

templateId*string

Template UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

categories?array<>|

Evaluation categories

description?string

Template description

judge_model?string

Judge LLM model

max_tokens?integer

Max tokens

Formatint32

name?string

Template name

scoring_rubric?string

Scoring rubric prompt

temperature?number

Sampling temperature

Formatdouble

Response Body

`application/json`

`application/problem+json`

curl -X PUT "https://loading/api/v1/eval-templates/string" \  -H "Content-Type: application/json" \  -d '{}'

{
  "$schema": "/api/v1/schemas/EvalTemplate.json",
  "categories": [
    {
      "key": "string",
      "label": "string",
      "prompt_instructions": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "description": "string",
  "is_system": true,
  "judge_model": "string",
  "max_tokens": 0,
  "name": "string",
  "scoring_rubric": "string",
  "temperature": 0.1,
  "template_id": "string",
  "template_type": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z"
}

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

Evals

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200text/event-stream

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`text/event-stream`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`