Ctrlk
Go to website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Simulations

List Simulation Runs

get
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Query parameters
service_idstring · uuid · nullableOptional
limitintegerOptionalDefault: 20
Responses
200

Successful Response

application/json
Other propertiesanyOptional
get/v1/{workspace_id}/simulations/runs
GET /v1/{workspace_id}/simulations/runs HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Create Simulation Run

post

Create a simulation coverage run with an optional Lakebase branch.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Body
service_idstring · uuidRequired
branch_namestring · max: 64 · nullableOptional
tagsstring[] · max: 20Optional
Responses
200

Successful Response

application/json
Other propertiesanyOptional
post/v1/{workspace_id}/simulations/runs
POST /v1/{workspace_id}/simulations/runs HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 90

{
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "branch_name": "text",
  "tags": [
    "text"
  ]
}
{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Get Simulation Runs Summary

get

Aggregate run counts (total + by status) for the Runs summary strip.

Registered before /runs/{run_id} so the static summary path segment is matched here rather than parsed as a run UUID (which would 422).

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Query parameters
service_idstring · uuid · nullableOptional
Responses
200

Successful Response

application/json

Aggregate counts across a workspace's simulation runs, for the Runs page summary strip.

A cheap GROUP BY status over world.simulation_coverage_runs — honest totals the 50-row list view cannot derive client-side. by_status carries the full breakdown (incl. any status beyond the three named convenience fields) so a new lifecycle state surfaces without a schema change.

totalintegerRequired
runningintegerRequired
completedintegerRequired
failedintegerRequired
total_sessionsintegerRequired
total_turnsintegerRequired
last_created_atstring · nullableOptional
get/v1/{workspace_id}/simulations/runs/summary
GET /v1/{workspace_id}/simulations/runs/summary HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "total": 1,
  "running": 1,
  "completed": 1,
  "failed": 1,
  "by_status": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "total_sessions": 1,
  "total_turns": 1,
  "last_created_at": "text"
}

List Simulation Suites

get

List first-class simulation suites.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Responses
200

Successful Response

application/json
get/v1/{workspace_id}/simulations/suites
GET /v1/{workspace_id}/simulations/suites HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Successful Response

{
  "suites": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "",
      "case_ids": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "required_tags": [
        "text"
      ],
      "tags": [
        "text"
      ],
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "case_count": 1,
      "created_by": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Create Simulation Suite

post

Create a reusable suite definition for saved simulation cases.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Body
namestring · min: 1 · max: 128Required
descriptionstring · max: 2000OptionalDefault: ""
case_idsstring · uuid[] · max: 500Optional
required_tagsstring[] · max: 20Optional
tagsstring[] · max: 20Optional
Responses
200

Successful Response

application/json

HTTP response shape for first-class simulation suites.

idstring · uuidRequired
workspace_idstring · uuidRequired
namestring · max: 128Required
descriptionstring · max: 2000OptionalDefault: ""
case_idsstring · uuid[]Optional
required_tagsstring[]Optional
tagsstring[]Optional
case_countintegerRequired
created_bystring · uuid · nullableOptional
created_atstring · date-time · nullableOptional
updated_atstring · date-time · nullableOptional
post/v1/{workspace_id}/simulations/suites
POST /v1/{workspace_id}/simulations/suites HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 175

{
  "name": "text",
  "description": "",
  "case_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "required_tags": [
    "text"
  ],
  "tags": [
    "text"
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "",
  "case_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "required_tags": [
    "text"
  ],
  "tags": [
    "text"
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "case_count": 1,
  "created_by": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Get Simulation Suite

get
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
suite_idstring · uuidRequired
Responses
200

Successful Response

application/json

HTTP response shape for first-class simulation suites.

idstring · uuidRequired
workspace_idstring · uuidRequired
namestring · max: 128Required
descriptionstring · max: 2000OptionalDefault: ""
case_idsstring · uuid[]Optional
required_tagsstring[]Optional
tagsstring[]Optional
case_countintegerRequired
created_bystring · uuid · nullableOptional
created_atstring · date-time · nullableOptional
updated_atstring · date-time · nullableOptional
get/v1/{workspace_id}/simulations/suites/{suite_id}
GET /v1/{workspace_id}/simulations/suites/{suite_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "",
  "case_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "required_tags": [
    "text"
  ],
  "tags": [
    "text"
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "case_count": 1,
  "created_by": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Delete Simulation Suite

delete
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
suite_idstring · uuidRequired
Responses
204

Successful Response

No content
delete/v1/{workspace_id}/simulations/suites/{suite_id}
DELETE /v1/{workspace_id}/simulations/suites/{suite_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update Simulation Suite

patch
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
suite_idstring · uuidRequired
Body
namestring · min: 1 · max: 128 · nullableOptional
descriptionstring · max: 2000 · nullableOptional
case_idsstring · uuid[] · max: 500 · nullableOptional
required_tagsstring[] · max: 20 · nullableOptional
tagsstring[] · max: 20 · nullableOptional
Responses
200

Successful Response

application/json

HTTP response shape for first-class simulation suites.

idstring · uuidRequired
workspace_idstring · uuidRequired
namestring · max: 128Required
descriptionstring · max: 2000OptionalDefault: ""
case_idsstring · uuid[]Optional
required_tagsstring[]Optional
tagsstring[]Optional
case_countintegerRequired
created_bystring · uuid · nullableOptional
created_atstring · date-time · nullableOptional
updated_atstring · date-time · nullableOptional
patch/v1/{workspace_id}/simulations/suites/{suite_id}
PATCH /v1/{workspace_id}/simulations/suites/{suite_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 179

{
  "name": "text",
  "description": "text",
  "case_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "required_tags": [
    "text"
  ],
  "tags": [
    "text"
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "",
  "case_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "required_tags": [
    "text"
  ],
  "tags": [
    "text"
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "case_count": 1,
  "created_by": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

List Simulation Suite Runs

get

List durable suite-run groups for a first-class suite.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
suite_idstring · uuidRequired
Query parameters
limitinteger · min: 1 · max: 50OptionalDefault: 20
Responses
200

Successful Response

application/json
suite_idstring · uuidRequired
get/v1/{workspace_id}/simulations/suites/{suite_id}/runs
GET /v1/{workspace_id}/simulations/suites/{suite_id}/runs HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "suite_id": "123e4567-e89b-12d3-a456-426614174000",
  "runs": [
    {
      "suite_run_id": "123e4567-e89b-12d3-a456-426614174000",
      "suite_id": "123e4567-e89b-12d3-a456-426614174000",
      "run_ids": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "total_runs": 1,
      "expected_case_count": 1,
      "status": "running",
      "status_counts": {
        "ANY_ADDITIONAL_PROPERTY": 1
      },
      "case_ids": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "total_sessions": 0,
      "total_turns": 0,
      "tags": [
        "text"
      ],
      "created_at": "text",
      "completed_at": "text",
      "result_pointer": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ]
}

List Simulation Cases

get

List durable simulation cases for case-library inspection.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Query parameters
limitinteger · max: 200OptionalDefault: 50
continuation_tokenanyOptional
service_idstring · uuid · nullableOptional
tagsstring[] · max: 20 · nullableOptional
Responses
200

Successful Response

application/json
has_morebooleanRequired
continuation_tokenanyOptional
get/v1/{workspace_id}/simulations/cases
GET /v1/{workspace_id}/simulations/cases HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "service_id": "123e4567-e89b-12d3-a456-426614174000",
      "description": "text",
      "persona": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "scenario": {
        "instructions": "text",
        "initial_message": "",
        "temperament": "text"
      },
      "grounding": {
        "patient_entity_id": "123e4567-e89b-12d3-a456-426614174000"
      },
      "evals": [
        {
          "type": "text",
          "metric_key": "text",
          "expected": null,
          "params": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "weight": 1
        }
      ],
      "tags": [
        "text"
      ],
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "created_by": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Create Simulation Cases

post

Create durable simulation cases for an internal benchmark suite.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Body
Responses
200

Successful Response

application/json
post/v1/{workspace_id}/simulations/cases
POST /v1/{workspace_id}/simulations/cases HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 472

{
  "cases": [
    {
      "service_id": "123e4567-e89b-12d3-a456-426614174000",
      "description": "text",
      "persona": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "scenario": {
        "instructions": "text",
        "initial_message": "",
        "temperament": "text"
      },
      "grounding": {
        "patient_entity_id": "123e4567-e89b-12d3-a456-426614174000"
      },
      "evals": [
        {
          "type": "text",
          "metric_key": "text",
          "expected": null,
          "params": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "weight": 1
        }
      ],
      "tags": [
        "text"
      ],
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ]
}
{
  "cases": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "service_id": "123e4567-e89b-12d3-a456-426614174000",
      "description": "text",
      "persona": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "scenario": {
        "instructions": "text",
        "initial_message": "",
        "temperament": "text"
      },
      "grounding": {
        "patient_entity_id": "123e4567-e89b-12d3-a456-426614174000"
      },
      "evals": [
        {
          "type": "text",
          "metric_key": "text",
          "expected": null,
          "params": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "weight": 1
        }
      ],
      "tags": [
        "text"
      ],
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "created_by": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Get Simulation Case

get

Fetch one durable simulation case for case-library inspection.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
case_idstring · uuidRequired
Responses
200

Successful Response

application/json

HTTP response shape for durable simulation cases.

idstring · uuidRequired
workspace_idstring · uuidRequired
service_idstring · uuid · nullableOptional
descriptionstring · max: 2000Required
tagsstring[]Optional
created_bystring · uuid · nullableOptional
created_atstring · date-time · nullableOptional
updated_atstring · date-time · nullableOptional
get/v1/{workspace_id}/simulations/cases/{case_id}
GET /v1/{workspace_id}/simulations/cases/{case_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "description": "text",
  "persona": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "scenario": {
    "instructions": "text",
    "initial_message": "",
    "temperament": "text"
  },
  "grounding": {
    "patient_entity_id": "123e4567-e89b-12d3-a456-426614174000"
  },
  "evals": [
    {
      "type": "text",
      "metric_key": "text",
      "expected": null,
      "params": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "weight": 1
    }
  ],
  "tags": [
    "text"
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "created_by": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Delete Simulation Case

delete

Delete one durable simulation case.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
case_idstring · uuidRequired
Responses
204

Successful Response

No content
delete/v1/{workspace_id}/simulations/cases/{case_id}
DELETE /v1/{workspace_id}/simulations/cases/{case_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update Simulation Case

patch

Update editable fields on one durable simulation case.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
case_idstring · uuidRequired
Body

Partial update for one durable simulation case.

Mirrors the nested CreateSimulationCaseItem shape with every field optional so model_dump(exclude_unset=True) only emits the keys the caller actually sent. Reuses the same nested submodels as create so the durable fields (scenario, grounding, evals, metadata) can be PATCHed. extra="forbid" rejects the retired pre-V192 flat fields (scenario_instructions, initial_message, temperament, fixtures, constraints, target_spec, assertions, provenance) with 422 instead of silently dropping them.

service_idstring · uuid · nullableOptional
descriptionstring · min: 1 · max: 2000 · nullableOptional
tagsstring[] · max: 20 · nullableOptional
Responses
200

Successful Response

application/json

HTTP response shape for durable simulation cases.

idstring · uuidRequired
workspace_idstring · uuidRequired
service_idstring · uuid · nullableOptional
descriptionstring · max: 2000Required
tagsstring[]Optional
created_bystring · uuid · nullableOptional
created_atstring · date-time · nullableOptional
updated_atstring · date-time · nullableOptional
patch/v1/{workspace_id}/simulations/cases/{case_id}
PATCH /v1/{workspace_id}/simulations/cases/{case_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 460

{
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "persona": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "description": "text",
  "scenario": {
    "instructions": "text",
    "initial_message": "",
    "temperament": "text"
  },
  "grounding": {
    "patient_entity_id": "123e4567-e89b-12d3-a456-426614174000"
  },
  "evals": [
    {
      "type": "text",
      "metric_key": "text",
      "expected": null,
      "params": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "weight": 1
    }
  ],
  "tags": [
    "text"
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "description": "text",
  "persona": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "scenario": {
    "instructions": "text",
    "initial_message": "",
    "temperament": "text"
  },
  "grounding": {
    "patient_entity_id": "123e4567-e89b-12d3-a456-426614174000"
  },
  "evals": [
    {
      "type": "text",
      "metric_key": "text",
      "expected": null,
      "params": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "weight": 1
    }
  ],
  "tags": [
    "text"
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "created_by": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Get Simulation Run

get

Fetch a single run including objective / bridge_request / scenarios.

Use the bridge_request payload to re-POST /bridge and replay the run.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
run_idstring · uuidRequired
Responses
200

Successful Response

application/json

Full run payload — used by GET /runs/{run_id} for replay flows.

idstring · uuidRequired
service_idstring · uuidRequired
branch_namestring · max: 64 · nullableOptional
statusstring · enumRequiredPossible values:
errorstring · max: 500 · nullableOptional
tagsstring[]Optional
total_sessionsintegerOptionalDefault: 0
total_turnsintegerOptionalDefault: 0
objectivestring · max: 2000 · nullableOptional
total_scenarios_requestedinteger · nullableOptional
created_atstring · nullableOptional
completed_atstring · nullableOptional
metric_statusstring · enumOptionalDefault: pendingPossible values:
metric_result_countintegerOptionalDefault: 0
metrics_last_checked_atstring · date-time · nullableOptional
eval_result_countintegerOptionalDefault: 0
eval_pass_countintegerOptionalDefault: 0
eval_fail_countintegerOptionalDefault: 0
eval_error_countintegerOptionalDefault: 0
get/v1/{workspace_id}/simulations/runs/{run_id}
GET /v1/{workspace_id}/simulations/runs/{run_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "branch_name": "text",
  "status": "running",
  "error": "text",
  "tags": [
    "text"
  ],
  "total_sessions": 0,
  "total_turns": 0,
  "objective": "text",
  "bridge_request": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "scenarios": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "snapshot": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "total_scenarios_requested": 1,
  "created_at": "text",
  "completed_at": "text",
  "metric_status": "pending",
  "metric_result_count": 0,
  "metrics_last_checked_at": "2026-01-01T00:00:00.000Z",
  "eval_results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "run_id": "123e4567-e89b-12d3-a456-426614174000",
      "case_id": "123e4567-e89b-12d3-a456-426614174000",
      "session_id": "text",
      "eval_key": "text",
      "eval_type": "assertion",
      "assertion_kind": "text",
      "metric_key": "text",
      "status": "passed",
      "passed": true,
      "score": 1,
      "expected": null,
      "actual": null,
      "rationale": "text",
      "justification": "text",
      "references": [
        1
      ],
      "details": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "definition": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "created_at": "text"
    }
  ],
  "eval_result_count": 0,
  "eval_pass_count": 0,
  "eval_fail_count": 0,
  "eval_error_count": 0,
  "checks": [
    {
      "source_type": "metric",
      "key": "text",
      "label": "text",
      "value_type": "numeric",
      "evaluation_method": "threshold",
      "expected": null,
      "actual": null,
      "expected_display": "text",
      "actual_display": "text",
      "verdict": "passed",
      "score": 1,
      "score_label": "text",
      "rationale": "text",
      "references": [
        1
      ],
      "run_id": "text",
      "case_id": "text",
      "session_id": "text",
      "trace_id": "text"
    }
  ]
}

Get Simulation Performance

get

Aggregate recent graded (case/suite) runs into the Simulations overview: overall pass rate, per-metric trend series, and per-case / per-suite rollups (each with its per-conversation verdicts).

limit bounds how many recent runs are read (capped at 50). One request replaces the console's former one-fetch-per-run fan-out.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Query parameters
service_idstring · uuid · nullableOptional
limitintegerOptionalDefault: 15
Responses
200

Successful Response

application/json

Aggregated Simulations overview: one request in place of the console's former one-detail-fetch-per-run fan-out.

get/v1/{workspace_id}/simulations/performance
GET /v1/{workspace_id}/simulations/performance HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "overview": {
    "overall_pass_rate": 1,
    "evals_run": 0,
    "needs_attention_count": 0,
    "runs_analyzed": 0
  },
  "metrics": [
    {
      "metric_key": "text",
      "label": "text",
      "per_run": [
        {
          "at": "text",
          "value": 1,
          "passed": 0,
          "measured": 0
        }
      ],
      "results": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "run_id": "123e4567-e89b-12d3-a456-426614174000",
          "case_id": "123e4567-e89b-12d3-a456-426614174000",
          "session_id": "text",
          "eval_key": "text",
          "eval_type": "assertion",
          "assertion_kind": "text",
          "metric_key": "text",
          "status": "passed",
          "passed": true,
          "score": 1,
          "expected": null,
          "actual": null,
          "rationale": "text",
          "justification": "text",
          "references": [
            1
          ],
          "details": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "definition": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "created_at": "text"
        }
      ],
      "checks": [
        {
          "source_type": "metric",
          "key": "text",
          "label": "text",
          "value_type": "numeric",
          "evaluation_method": "threshold",
          "expected": null,
          "actual": null,
          "expected_display": "text",
          "actual_display": "text",
          "verdict": "passed",
          "score": 1,
          "score_label": "text",
          "rationale": "text",
          "references": [
            1
          ],
          "run_id": "text",
          "case_id": "text",
          "session_id": "text",
          "trace_id": "text"
        }
      ]
    }
  ],
  "by_case": [
    {
      "case_id": "123e4567-e89b-12d3-a456-426614174000",
      "case_name": "text",
      "pass_rate": 1,
      "passed": 0,
      "measured": 0,
      "latest_run_id": "123e4567-e89b-12d3-a456-426614174000",
      "latest_run_at": "text",
      "assertions": [
        {
          "eval_key": "text",
          "eval_type": "assertion",
          "passed": 0,
          "failed": 0,
          "pending": 0,
          "pass_rate": 1,
          "results": [
            {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "run_id": "123e4567-e89b-12d3-a456-426614174000",
              "case_id": "123e4567-e89b-12d3-a456-426614174000",
              "session_id": "text",
              "eval_key": "text",
              "eval_type": "assertion",
              "assertion_kind": "text",
              "metric_key": "text",
              "status": "passed",
              "passed": true,
              "score": 1,
              "expected": null,
              "actual": null,
              "rationale": "text",
              "justification": "text",
              "references": [
                1
              ],
              "details": {
                "ANY_ADDITIONAL_PROPERTY": "anything"
              },
              "definition": {
                "ANY_ADDITIONAL_PROPERTY": "anything"
              },
              "created_at": "text"
            }
          ],
          "checks": [
            {
              "source_type": "metric",
              "key": "text",
              "label": "text",
              "value_type": "numeric",
              "evaluation_method": "threshold",
              "expected": null,
              "actual": null,
              "expected_display": "text",
              "actual_display": "text",
              "verdict": "passed",
              "score": 1,
              "score_label": "text",
              "rationale": "text",
              "references": [
                1
              ],
              "run_id": "text",
              "case_id": "text",
              "session_id": "text",
              "trace_id": "text"
            }
          ]
        }
      ]
    }
  ],
  "by_suite": [
    {
      "suite_id": "123e4567-e89b-12d3-a456-426614174000",
      "suite_name": "text",
      "pass_rate": 1,
      "passed": 0,
      "measured": 0,
      "latest_run_at": "text",
      "cases": [
        {
          "case_id": "123e4567-e89b-12d3-a456-426614174000",
          "case_name": "text",
          "pass_rate": 1,
          "passed": 0,
          "measured": 0,
          "latest_run_id": "123e4567-e89b-12d3-a456-426614174000",
          "latest_run_at": "text",
          "assertions": [
            {
              "eval_key": "text",
              "eval_type": "assertion",
              "passed": 0,
              "failed": 0,
              "pending": 0,
              "pass_rate": 1,
              "results": [
                {
                  "id": "123e4567-e89b-12d3-a456-426614174000",
                  "run_id": "123e4567-e89b-12d3-a456-426614174000",
                  "case_id": "123e4567-e89b-12d3-a456-426614174000",
                  "session_id": "text",
                  "eval_key": "text",
                  "eval_type": "assertion",
                  "assertion_kind": "text",
                  "metric_key": "text",
                  "status": "passed",
                  "passed": true,
                  "score": 1,
                  "expected": null,
                  "actual": null,
                  "rationale": "text",
                  "justification": "text",
                  "references": [
                    1
                  ],
                  "details": {
                    "ANY_ADDITIONAL_PROPERTY": "anything"
                  },
                  "definition": {
                    "ANY_ADDITIONAL_PROPERTY": "anything"
                  },
                  "created_at": "text"
                }
              ],
              "checks": [
                {
                  "source_type": "metric",
                  "key": "text",
                  "label": "text",
                  "value_type": "numeric",
                  "evaluation_method": "threshold",
                  "expected": null,
                  "actual": null,
                  "expected_display": "text",
                  "actual_display": "text",
                  "verdict": "passed",
                  "score": 1,
                  "score_label": "text",
                  "rationale": "text",
                  "references": [
                    1
                  ],
                  "run_id": "text",
                  "case_id": "text",
                  "session_id": "text",
                  "trace_id": "text"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Complete Simulation Run

post
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
run_idstring · uuidRequired
Query parameters
errorstring · nullableOptional
Responses
200

Successful Response

application/json
Other propertiesstringOptional
post/v1/{workspace_id}/simulations/runs/{run_id}/complete
POST /v1/{workspace_id}/simulations/runs/{run_id}/complete HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "text"
}

Promote Simulation Session

post

Promote a run-less (interactive playground) session into a coverage run.

Interactive text sessions are created run-less, so fork — which requires a run_id — 404s on them. This creates a coverage run, binds the existing agent-engine session to it (adopt-run, a Valkey meta update — the session itself is not recreated), and writes the platform-api SimulationCoverageSession record that get_session_metadata returns, unblocking fork/score.

Idempotent: a session that already has a coverage record returns its existing run with already_bound=True.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
session_idstringRequired
Responses
200

Successful Response

application/json

Result of binding a run-less session to a (newly created) coverage run.

run_idstring · uuidRequired

The coverage run the session is now bound to

session_idstringRequired

The promoted session id (unchanged)

already_boundbooleanRequired

True when the session was already run-scoped; the existing run is returned unchanged

post/v1/{workspace_id}/simulations/sessions/{session_id}/promote
POST /v1/{workspace_id}/simulations/sessions/{session_id}/promote HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "run_id": "123e4567-e89b-12d3-a456-426614174000",
  "session_id": "text",
  "already_bound": true
}

Create Simulation Session

post

Create a simulation session within a run. Proxies to agent-engine.

entity_id ownership: agent-engine's _resolve_caller queries the entity with workspace_id scoping — a workspace-A entity_id resolves to None in workspace-B, so no cross-tenant data is exposed.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
run_idstring · uuidRequired
Body
service_idstring · uuidRequired
branch_namestring · max: 64 · nullableOptional
tagsstring[] · max: 20Optional
caller_idstring · max: 64 · nullableOptional

Simulated caller phone number used to resolve patient context when entity_id is not provided (or does not match a row). Omitted/blank values are normalized to the sim-orchestrator sentinel, which yields no phone match and an empty caller context — same default the voice test-call WebSocket uses, so patient lookups resolve consistently across modalities.

entity_idstring · uuid · nullableOptional

Optional world entity UUID to bind caller context directly. Precedence rules: (1) when this resolves to a world entity in the workspace, it WINS — caller_id is not used for identity resolution, and the resolution provenance is entity_id_lookup; (2) when this is a well-formed UUID with no matching entity (stale, deleted, wrong workspace), the session falls back to phone lookup against caller_id (provenance phone_lookup) — no error is raised, the sim is survivable; (3) malformed UUIDs are rejected with HTTP 422 before the request reaches agent-engine. The supplied caller_id is still recorded on the active call and surfaced in the greeting metadata in case (1).

Responses
200

Successful Response

application/json
session_idstringRequired
greetingstringRequired
is_terminalbooleanRequired
post/v1/{workspace_id}/simulations/runs/{run_id}/sessions
POST /v1/{workspace_id}/simulations/runs/{run_id}/sessions HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 160

{
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "branch_name": "text",
  "tags": [
    "text"
  ],
  "caller_id": "text",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000"
}
{
  "session_id": "text",
  "greeting": "text",
  "is_terminal": true,
  "snapshot": {
    "current_state": {
      "name": "text",
      "type": "text",
      "objective": "",
      "actions": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "exit_conditions": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "action_guidelines": [
        "text"
      ],
      "boundary_constraints": [
        "text"
      ],
      "guardrails": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "tools": [
        "text"
      ],
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "reachable_states": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "turn_policy": {
      "barge_in_enabled": true,
      "greeting_shield_s": 0,
      "safety_response": "suspend_forward",
      "context_strategy": "full",
      "block_forward_call": false,
      "block_forward_call_after_turns": -1
    },
    "conversation_history": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "states_visited": [
      "text"
    ],
    "state_transitions": [
      [
        "text"
      ]
    ],
    "total_turns": 0,
    "tools_called": [
      "text"
    ],
    "terminal_reached": false,
    "context_graph_topology": [
      {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    ],
    "terminal_state": "text",
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Simulation Step

post

Step a simulation session and auto-store the turn observation.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
session_idstringRequired
Body
session_idstring · max: 64Required
caller_textstring · max: 2000Required
emotionstring · max: 50 · nullableOptional
valencenumber · min: -1 · max: 1 · nullableOptional
Responses
200

Successful Response

application/json
post/v1/{workspace_id}/simulations/sessions/{session_id}/step
POST /v1/{workspace_id}/simulations/sessions/{session_id}/step HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "session_id": "text",
  "caller_text": "text",
  "emotion": "text",
  "valence": 1
}
{
  "observation": {
    "state_before": "text",
    "state_after": "text",
    "state_changed": true,
    "agent_text": "text",
    "is_terminal": true,
    "tools_called": [
      "text"
    ],
    "tool_call_details": [
      {
        "tool_name": "text",
        "input": "",
        "result": "",
        "call_id": "",
        "succeeded": true
      }
    ],
    "selected_action": "text",
    "empathy_tier": 0,
    "has_pause": false,
    "engine_ms": 1,
    "nav_ms": 1
  },
  "snapshot": {
    "current_state": {
      "name": "text",
      "type": "text",
      "objective": "",
      "actions": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "exit_conditions": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "action_guidelines": [
        "text"
      ],
      "boundary_constraints": [
        "text"
      ],
      "guardrails": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "tools": [
        "text"
      ],
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "reachable_states": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "turn_policy": {
      "barge_in_enabled": true,
      "greeting_shield_s": 0,
      "safety_response": "suspend_forward",
      "context_strategy": "full",
      "block_forward_call": false,
      "block_forward_call_after_turns": -1
    },
    "conversation_history": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "states_visited": [
      "text"
    ],
    "state_transitions": [
      [
        "text"
      ]
    ],
    "total_turns": 0,
    "tools_called": [
      "text"
    ],
    "terminal_reached": false,
    "context_graph_topology": [
      {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    ],
    "terminal_state": "text",
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Simulation Fork

post

Fork a session into N branches — clone + step each alternative atomically.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
session_idstringRequired
Body
Responses
200

Successful Response

application/json
Other propertiesanyOptional
post/v1/{workspace_id}/simulations/sessions/{session_id}/fork
POST /v1/{workspace_id}/simulations/sessions/{session_id}/fork HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 70

{
  "alternatives": [
    {
      "caller_text": "text",
      "emotion": "text",
      "valence": 1
    }
  ]
}
{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Score Simulation Session

post

ASI assigns a score to a completed simulation session.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
session_idstringRequired
Body
scorenumber · max: 100Required
score_rationalestring · max: 2000 · nullableOptional
Responses
200

Successful Response

application/json
Other propertiesstringOptional
post/v1/{workspace_id}/simulations/sessions/{session_id}/score
POST /v1/{workspace_id}/simulations/sessions/{session_id}/score HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "score": 1,
  "score_rationale": "text"
}
{
  "ANY_ADDITIONAL_PROPERTY": "text"
}

Create Test Conversation

post

Create a test conversation session (no coverage run required).

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Body
service_idstring · uuidRequired
branch_namestring · max: 64 · nullableOptional
tagsstring[] · max: 20Optional
caller_idstring · max: 64 · nullableOptional

Simulated caller phone number used to resolve patient context when entity_id is not provided (or does not match a row). Omitted/blank values are normalized to the sim-orchestrator sentinel, which yields no phone match and an empty caller context — same default the voice test-call WebSocket uses, so patient lookups resolve consistently across modalities.

entity_idstring · uuid · nullableOptional

Optional world entity UUID to bind caller context directly. Precedence rules: (1) when this resolves to a world entity in the workspace, it WINS — caller_id is not used for identity resolution, and the resolution provenance is entity_id_lookup; (2) when this is a well-formed UUID with no matching entity (stale, deleted, wrong workspace), the session falls back to phone lookup against caller_id (provenance phone_lookup) — no error is raised, the sim is survivable; (3) malformed UUIDs are rejected with HTTP 422 before the request reaches agent-engine. The supplied caller_id is still recorded on the active call and surfaced in the greeting metadata in case (1).

Responses
200

Successful Response

application/json
session_idstringRequired
greetingstringRequired
is_terminalbooleanRequired
post/v1/{workspace_id}/simulations/sessions
POST /v1/{workspace_id}/simulations/sessions HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 160

{
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "branch_name": "text",
  "tags": [
    "text"
  ],
  "caller_id": "text",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000"
}
{
  "session_id": "text",
  "greeting": "text",
  "is_terminal": true,
  "snapshot": {
    "current_state": {
      "name": "text",
      "type": "text",
      "objective": "",
      "actions": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "exit_conditions": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "action_guidelines": [
        "text"
      ],
      "boundary_constraints": [
        "text"
      ],
      "guardrails": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "tools": [
        "text"
      ],
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "reachable_states": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "turn_policy": {
      "barge_in_enabled": true,
      "greeting_shield_s": 0,
      "safety_response": "suspend_forward",
      "context_strategy": "full",
      "block_forward_call": false,
      "block_forward_call_after_turns": -1
    },
    "conversation_history": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "states_visited": [
      "text"
    ],
    "state_transitions": [
      [
        "text"
      ]
    ],
    "total_turns": 0,
    "tools_called": [
      "text"
    ],
    "terminal_reached": false,
    "context_graph_topology": [
      {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    ],
    "terminal_state": "text",
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Test Conversation Step

post

Step a test conversation (no coverage auto-store).

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Body
session_idstring · max: 64Required
caller_textstring · max: 2000Required
emotionstring · max: 50 · nullableOptional
valencenumber · min: -1 · max: 1 · nullableOptional
Responses
200

Successful Response

application/json
post/v1/{workspace_id}/simulations/sessions/step
POST /v1/{workspace_id}/simulations/sessions/step HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "session_id": "text",
  "caller_text": "text",
  "emotion": "text",
  "valence": 1
}
{
  "observation": {
    "state_before": "text",
    "state_after": "text",
    "state_changed": true,
    "agent_text": "text",
    "is_terminal": true,
    "tools_called": [
      "text"
    ],
    "tool_call_details": [
      {
        "tool_name": "text",
        "input": "",
        "result": "",
        "call_id": "",
        "succeeded": true
      }
    ],
    "selected_action": "text",
    "empathy_tier": 0,
    "has_pause": false,
    "engine_ms": 1,
    "nav_ms": 1
  },
  "snapshot": {
    "current_state": {
      "name": "text",
      "type": "text",
      "objective": "",
      "actions": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "exit_conditions": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "action_guidelines": [
        "text"
      ],
      "boundary_constraints": [
        "text"
      ],
      "guardrails": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "tools": [
        "text"
      ],
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "reachable_states": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "turn_policy": {
      "barge_in_enabled": true,
      "greeting_shield_s": 0,
      "safety_response": "suspend_forward",
      "context_strategy": "full",
      "block_forward_call": false,
      "block_forward_call_after_turns": -1
    },
    "conversation_history": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "states_visited": [
      "text"
    ],
    "state_transitions": [
      [
        "text"
      ]
    ],
    "total_turns": 0,
    "tools_called": [
      "text"
    ],
    "terminal_reached": false,
    "context_graph_topology": [
      {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    ],
    "terminal_state": "text",
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Simulation Recommend

post
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Body
session_idstring · max: 64Required
ninteger · min: 1 · max: 20OptionalDefault: 5
Responses
200

Successful Response

application/json
suggestionsstring[] · max: 100Required

LLM-generated caller message suggestions

post/v1/{workspace_id}/simulations/sessions/recommend
POST /v1/{workspace_id}/simulations/sessions/recommend HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 27

{
  "session_id": "text",
  "n": 5
}
{
  "suggestions": [
    "text"
  ]
}

Simulation Observe

get
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
session_idstringRequired
Responses
200

Successful Response

application/json
states_visitedstring[]OptionalDefault: []
total_turnsintegerOptionalDefault: 0
tools_calledstring[]OptionalDefault: []
terminal_reachedbooleanOptionalDefault: false
terminal_statestring · nullableOptional
Other propertiesanyOptional
get/v1/{workspace_id}/simulations/sessions/{session_id}
GET /v1/{workspace_id}/simulations/sessions/{session_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "current_state": {
    "name": "text",
    "type": "text",
    "objective": "",
    "actions": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "exit_conditions": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "action_guidelines": [
      "text"
    ],
    "boundary_constraints": [
      "text"
    ],
    "guardrails": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "tools": [
      "text"
    ],
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "reachable_states": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "turn_policy": {
    "barge_in_enabled": true,
    "greeting_shield_s": 0,
    "safety_response": "suspend_forward",
    "context_strategy": "full",
    "block_forward_call": false,
    "block_forward_call_after_turns": -1
  },
  "conversation_history": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "states_visited": [
    "text"
  ],
  "state_transitions": [
    [
      "text"
    ]
  ],
  "total_turns": 0,
  "tools_called": [
    "text"
  ],
  "terminal_reached": false,
  "context_graph_topology": [
    {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  ],
  "terminal_state": "text",
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Simulation Destroy

delete
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
session_idstringRequired
Responses
200

Successful Response

application/json
statusconst: destroyedRequired

Session destruction status

delete/v1/{workspace_id}/simulations/sessions/{session_id}
DELETE /v1/{workspace_id}/simulations/sessions/{session_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "status": "text"
}

Simulation Intelligence

get
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
session_idstringRequired
Responses
200

Successful Response

application/json
session_idstringRequired
get/v1/{workspace_id}/simulations/sessions/{session_id}/intelligence
GET /v1/{workspace_id}/simulations/sessions/{session_id}/intelligence HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "session_id": "text",
  "intelligence": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Get Simulation Coverage Graph

get

Get the B&B knowledge graph for a service — topology + observations merged.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
service_idstring · uuidRequired
Query parameters
run_idstring · uuid · nullableOptional
include_turnsbooleanOptionalDefault: false
Responses
200

Successful Response

application/json
Other propertiesanyOptional
get/v1/{workspace_id}/simulations/services/{service_id}/graph
GET /v1/{workspace_id}/simulations/services/{service_id}/graph HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Delete Simulation Coverage Graph

delete
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
service_idstring · uuidRequired
Responses
200

Successful Response

application/json
Other propertiesanyOptional
delete/v1/{workspace_id}/simulations/services/{service_id}/graph
DELETE /v1/{workspace_id}/simulations/services/{service_id}/graph HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Get Simulation Coverage Paths

get

Get distinct trajectories from simulation sessions.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
service_idstring · uuidRequired
Query parameters
run_idstring · uuid · nullableOptional
Responses
200

Successful Response

application/json
Other propertiesanyOptional
get/v1/{workspace_id}/simulations/services/{service_id}/graph/paths
GET /v1/{workspace_id}/simulations/services/{service_id}/graph/paths HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

List Simulation Sessions

get
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
service_idstring · uuidRequired
Query parameters
run_idstring · uuid · nullableOptional
limitintegerOptionalDefault: 50
Responses
200

Successful Response

application/json
Other propertiesanyOptional
get/v1/{workspace_id}/simulations/services/{service_id}/sessions
GET /v1/{workspace_id}/simulations/services/{service_id}/sessions HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Get Simulation Session Turns

get
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
session_idstringRequired
Responses
200

Successful Response

application/json
Other propertiesanyOptional
get/v1/{workspace_id}/simulations/sessions/{session_id}/turns
GET /v1/{workspace_id}/simulations/sessions/{session_id}/turns HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Query Simulation Turns

get
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
service_idstring · uuidRequired
Query parameters
statestring · nullableOptional
from_statestring · nullableOptional
to_statestring · nullableOptional
limitintegerOptionalDefault: 100
Responses
200

Successful Response

application/json
Other propertiesanyOptional
get/v1/{workspace_id}/simulations/services/{service_id}/turns
GET /v1/{workspace_id}/simulations/services/{service_id}/turns HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Config To Turn Policy

post
Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Body
Responses
200

Successful Response

application/json
Other propertiesanyOptional
post/v1/{workspace_id}/simulations/config-to-policy
POST /v1/{workspace_id}/simulations/config-to-policy HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 49

{
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}
{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Simulation Bridge

post

NL objective to N autonomous scenarios against the tracked simulation primitives.

Returns immediately with run_id + generated scenarios. Scenarios run in the background via BridgeExecutor (lifecycle-managed, shutdown-drained). Completion events are emitted to Delta via world_emitter for SDP observability.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Body
service_idstring · uuidRequired
objectivestring · min: 1 · max: 2000Required
num_scenariosinteger · min: 1 · max: 50OptionalDefault: 5
max_turnsinteger · min: 1 · max: 40OptionalDefault: 20
concurrencyinteger · min: 1 · max: 20OptionalDefault: 3
branch_namestring · max: 64 · nullableOptional
entity_idstring · uuid · nullableOptional

Optional world entity UUID to bind caller context for every scenario session created by this bridge run. The value is forwarded to each scenario's session-create call and inherited by any forks; identical precedence rules apply per-session (entity match wins over phone, stale UUID falls back to phone lookup, malformed UUID returns 422). Use this to pin an entire regression suite to a specific test patient.

tagsstring[] · max: 20Optional
auto_target_specbooleanOptionalDefault: false
async_generationbooleanOptionalDefault: false
Responses
200

Successful Response

application/json
run_idstring · uuidRequired
statusstring · enumRequiredPossible values:
case_idsstring · uuid[]Optional
inferred_target_spec_rationalestring · max: 1000 · nullableOptional
post/v1/{workspace_id}/simulations/bridge
POST /v1/{workspace_id}/simulations/bridge HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 604

{
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "objective": "text",
  "num_scenarios": 5,
  "max_turns": 20,
  "concurrency": 3,
  "branch_name": "text",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "tags": [
    "text"
  ],
  "target_spec": {
    "desired_states": [
      "text"
    ],
    "non_desired_states": [
      {
        "state": "text",
        "mode": "hard"
      }
    ],
    "ordered_pathways": [
      {
        "id": "text",
        "sequence": [
          "text"
        ]
      }
    ],
    "completion_criteria": {
      "state_based": [
        "text"
      ],
      "tool_based": [
        "text"
      ]
    }
  },
  "exploration": {
    "coverage_driven_selection": false,
    "enable_forking": false,
    "max_forks_per_scenario": 2,
    "recommend_candidates": 3
  },
  "auto_target_spec": false,
  "async_generation": false
}
{
  "run_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "running",
  "scenarios": [
    {
      "description": "text",
      "temperament": "neutral",
      "initial_message": "text",
      "scenario_instructions": "text",
      "persona": {
        "name": "",
        "role": "patient",
        "communication_style": "",
        "default_language": "en-US",
        "background": ""
      },
      "case_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "case_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "inferred_target_spec": {
    "desired_states": [
      "text"
    ],
    "non_desired_states": [
      {
        "state": "text",
        "mode": "hard"
      }
    ],
    "ordered_pathways": [
      {
        "id": "text",
        "sequence": [
          "text"
        ]
      }
    ],
    "completion_criteria": {
      "state_based": [
        "text"
      ],
      "tool_based": [
        "text"
      ]
    }
  },
  "inferred_target_spec_rationale": "text"
}

Run Simulation Benchmark

post

Run a suite or tag-selected benchmark batch as one saved-case run per case.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Body
suite_idstring · uuid · nullableOptional
required_tagsstring[] · max: 20Optional
service_idstring · uuid · nullableOptional
entity_idstring · uuid · nullableOptional

Optional world entity UUID to bind caller context for every selected saved-case run. When omitted, each case falls back to fixtures.case_specific.entity_id if present.

max_casesinteger · min: 1 · max: 200OptionalDefault: 20
max_turnsinteger · min: 1 · max: 40OptionalDefault: 20
concurrencyinteger · min: 1 · max: 20OptionalDefault: 1
branch_namestring · max: 64 · nullableOptional
tagsstring[] · max: 20Optional
Responses
200

Successful Response

application/json
batch_idstring · uuidRequired
suite_idstring · uuid · nullableOptional
required_tagsstring[]Required
selected_case_idsstring · uuid[]Required
run_idsstring · uuid[]Required
post/v1/{workspace_id}/simulations/benchmarks/run
POST /v1/{workspace_id}/simulations/benchmarks/run HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 387

{
  "suite_id": "123e4567-e89b-12d3-a456-426614174000",
  "required_tags": [
    "text"
  ],
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "max_cases": 20,
  "max_turns": 20,
  "concurrency": 1,
  "branch_name": "text",
  "tags": [
    "text"
  ],
  "exploration": {
    "coverage_driven_selection": false,
    "enable_forking": false,
    "max_forks_per_scenario": 2,
    "recommend_candidates": 3
  }
}
{
  "batch_id": "123e4567-e89b-12d3-a456-426614174000",
  "suite_id": "123e4567-e89b-12d3-a456-426614174000",
  "required_tags": [
    "text"
  ],
  "selected_case_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "run_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "cases": [
    {
      "case_id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "started",
      "run_id": "123e4567-e89b-12d3-a456-426614174000",
      "service_id": "123e4567-e89b-12d3-a456-426614174000",
      "result_pointer": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "reason": "text"
    }
  ],
  "skipped_cases": [
    {
      "case_id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "started",
      "run_id": "123e4567-e89b-12d3-a456-426614174000",
      "service_id": "123e4567-e89b-12d3-a456-426614174000",
      "result_pointer": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "reason": "text"
    }
  ],
  "failed_to_start_cases": [
    {
      "case_id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "started",
      "run_id": "123e4567-e89b-12d3-a456-426614174000",
      "service_id": "123e4567-e89b-12d3-a456-426614174000",
      "result_pointer": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "reason": "text"
    }
  ],
  "aggregate_summary": {
    "selected_count": 1,
    "started_count": 1,
    "skipped_count": 1,
    "failed_to_start_count": 1,
    "status_counts": {
      "ANY_ADDITIONAL_PROPERTY": 1
    },
    "scored_count": 0,
    "average_score": 1
  }
}

Run Simulation Suite

post

Run a first-class suite definition.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
suite_idstring · uuidRequired
Body
suite_idstring · uuid · nullableOptional
required_tagsstring[] · max: 20Optional
service_idstring · uuid · nullableOptional
entity_idstring · uuid · nullableOptional

Optional world entity UUID to bind caller context for every selected saved-case run. When omitted, each case falls back to fixtures.case_specific.entity_id if present.

max_casesinteger · min: 1 · max: 200OptionalDefault: 20
max_turnsinteger · min: 1 · max: 40OptionalDefault: 20
concurrencyinteger · min: 1 · max: 20OptionalDefault: 1
branch_namestring · max: 64 · nullableOptional
tagsstring[] · max: 20Optional
Responses
200

Successful Response

application/json
batch_idstring · uuidRequired
suite_idstring · uuid · nullableOptional
required_tagsstring[]Required
selected_case_idsstring · uuid[]Required
run_idsstring · uuid[]Required
post/v1/{workspace_id}/simulations/suites/{suite_id}/run
POST /v1/{workspace_id}/simulations/suites/{suite_id}/run HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 387

{
  "suite_id": "123e4567-e89b-12d3-a456-426614174000",
  "required_tags": [
    "text"
  ],
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "max_cases": 20,
  "max_turns": 20,
  "concurrency": 1,
  "branch_name": "text",
  "tags": [
    "text"
  ],
  "exploration": {
    "coverage_driven_selection": false,
    "enable_forking": false,
    "max_forks_per_scenario": 2,
    "recommend_candidates": 3
  }
}
{
  "batch_id": "123e4567-e89b-12d3-a456-426614174000",
  "suite_id": "123e4567-e89b-12d3-a456-426614174000",
  "required_tags": [
    "text"
  ],
  "selected_case_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "run_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "cases": [
    {
      "case_id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "started",
      "run_id": "123e4567-e89b-12d3-a456-426614174000",
      "service_id": "123e4567-e89b-12d3-a456-426614174000",
      "result_pointer": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "reason": "text"
    }
  ],
  "skipped_cases": [
    {
      "case_id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "started",
      "run_id": "123e4567-e89b-12d3-a456-426614174000",
      "service_id": "123e4567-e89b-12d3-a456-426614174000",
      "result_pointer": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "reason": "text"
    }
  ],
  "failed_to_start_cases": [
    {
      "case_id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "started",
      "run_id": "123e4567-e89b-12d3-a456-426614174000",
      "service_id": "123e4567-e89b-12d3-a456-426614174000",
      "result_pointer": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "reason": "text"
    }
  ],
  "aggregate_summary": {
    "selected_count": 1,
    "started_count": 1,
    "skipped_count": 1,
    "failed_to_start_count": 1,
    "status_counts": {
      "ANY_ADDITIONAL_PROPERTY": 1
    },
    "scored_count": 0,
    "average_score": 1
  }
}

Get Simulation Benchmark Results

post

Aggregate benchmark results over the run ids returned by benchmark start.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Body
run_idsstring · uuid[] · min: 1 · max: 100Required
Responses
200

Successful Response

application/json
run_idsstring · uuid[]Required
total_runsintegerRequired
completed_countintegerOptionalDefault: 0
failed_countintegerOptionalDefault: 0
scored_countintegerOptionalDefault: 0
average_scorenumber · nullableOptional
pass_countintegerOptionalDefault: 0
fail_countintegerOptionalDefault: 0
metric_statusstring · enumOptionalDefault: pendingPossible values:
metric_result_countintegerOptionalDefault: 0
metrics_last_checked_atstring · date-time · nullableOptional
missing_run_idsstring · uuid[]Optional
post/v1/{workspace_id}/simulations/benchmarks/results
POST /v1/{workspace_id}/simulations/benchmarks/results HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 52

{
  "run_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}
{
  "run_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "total_runs": 1,
  "status_counts": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "completed_count": 0,
  "failed_count": 0,
  "scored_count": 0,
  "average_score": 1,
  "pass_count": 0,
  "fail_count": 0,
  "metric_status": "pending",
  "metric_result_count": 0,
  "metrics_last_checked_at": "2026-01-01T00:00:00.000Z",
  "per_run": [
    {
      "run_id": "123e4567-e89b-12d3-a456-426614174000",
      "service_id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "running",
      "error": "text",
      "tags": [
        "text"
      ],
      "case_ids": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "session_ids": [
        "text"
      ],
      "total_sessions": 0,
      "total_turns": 0,
      "terminal_session_count": 0,
      "scored_session_count": 0,
      "average_score": 1,
      "passed": true,
      "pass_count": 0,
      "fail_count": 0,
      "score_rationales": [
        "text"
      ],
      "capability_tags": [
        "text"
      ],
      "created_at": "text",
      "completed_at": "text",
      "result_pointer": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "immediate_average_score": 1,
      "immediate_passed": true,
      "immediate_pass_count": 0,
      "immediate_fail_count": 0,
      "metric_status": "pending",
      "metric_result_count": 0,
      "metrics_last_checked_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "capability_breakdown": {
    "ANY_ADDITIONAL_PROPERTY": {
      "run_count": 0,
      "status_counts": {
        "ANY_ADDITIONAL_PROPERTY": 1
      },
      "completed_count": 0,
      "failed_count": 0,
      "scored_count": 0,
      "average_score": 1,
      "pass_count": 0,
      "fail_count": 0
    }
  },
  "missing_run_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Get Simulation Suite Run Results

get

Fetch aggregate results for a durable suite run.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
suite_run_idstring · uuidRequired
Responses
200

Successful Response

application/json
run_idsstring · uuid[]Required
total_runsintegerRequired
completed_countintegerOptionalDefault: 0
failed_countintegerOptionalDefault: 0
scored_countintegerOptionalDefault: 0
average_scorenumber · nullableOptional
pass_countintegerOptionalDefault: 0
fail_countintegerOptionalDefault: 0
metric_statusstring · enumOptionalDefault: pendingPossible values:
metric_result_countintegerOptionalDefault: 0
metrics_last_checked_atstring · date-time · nullableOptional
missing_run_idsstring · uuid[]Optional
suite_run_idstring · uuidRequired
suite_idstring · uuid · nullableOptional
get/v1/{workspace_id}/simulations/suite-runs/{suite_run_id}
GET /v1/{workspace_id}/simulations/suite-runs/{suite_run_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "run_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "total_runs": 1,
  "status_counts": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "completed_count": 0,
  "failed_count": 0,
  "scored_count": 0,
  "average_score": 1,
  "pass_count": 0,
  "fail_count": 0,
  "metric_status": "pending",
  "metric_result_count": 0,
  "metrics_last_checked_at": "2026-01-01T00:00:00.000Z",
  "per_run": [
    {
      "run_id": "123e4567-e89b-12d3-a456-426614174000",
      "service_id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "running",
      "error": "text",
      "tags": [
        "text"
      ],
      "case_ids": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "session_ids": [
        "text"
      ],
      "total_sessions": 0,
      "total_turns": 0,
      "terminal_session_count": 0,
      "scored_session_count": 0,
      "average_score": 1,
      "passed": true,
      "pass_count": 0,
      "fail_count": 0,
      "score_rationales": [
        "text"
      ],
      "capability_tags": [
        "text"
      ],
      "created_at": "text",
      "completed_at": "text",
      "result_pointer": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "immediate_average_score": 1,
      "immediate_passed": true,
      "immediate_pass_count": 0,
      "immediate_fail_count": 0,
      "metric_status": "pending",
      "metric_result_count": 0,
      "metrics_last_checked_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "capability_breakdown": {
    "ANY_ADDITIONAL_PROPERTY": {
      "run_count": 0,
      "status_counts": {
        "ANY_ADDITIONAL_PROPERTY": 1
      },
      "completed_count": 0,
      "failed_count": 0,
      "scored_count": 0,
      "average_score": 1,
      "pass_count": 0,
      "fail_count": 0
    }
  },
  "missing_run_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "suite_run_id": "123e4567-e89b-12d3-a456-426614174000",
  "suite_id": "123e4567-e89b-12d3-a456-426614174000",
  "summary": {
    "suite_run_id": "123e4567-e89b-12d3-a456-426614174000",
    "suite_id": "123e4567-e89b-12d3-a456-426614174000",
    "run_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "total_runs": 1,
    "expected_case_count": 1,
    "status": "running",
    "status_counts": {
      "ANY_ADDITIONAL_PROPERTY": 1
    },
    "case_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "total_sessions": 0,
    "total_turns": 0,
    "tags": [
      "text"
    ],
    "created_at": "text",
    "completed_at": "text",
    "result_pointer": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}

Run Simulation Case

post

Run the current saved simulation case through the bridge executor.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
case_idstring · uuidRequired
Body
service_idstring · uuid · nullableOptional
entity_idstring · uuid · nullableOptional

Optional world entity UUID to bind caller context for this saved-case run. When omitted, the runner falls back to fixtures.case_specific.entity_id if present.

max_turnsinteger · min: 1 · max: 40OptionalDefault: 20
concurrencyinteger · min: 1 · max: 20OptionalDefault: 1
branch_namestring · max: 64 · nullableOptional
tagsstring[] · max: 20Optional
Responses
200

Successful Response

application/json
run_idstring · uuidRequired
statusstring · enumRequiredPossible values:
case_idsstring · uuid[]Optional
inferred_target_spec_rationalestring · max: 1000 · nullableOptional
post/v1/{workspace_id}/simulations/cases/{case_id}/run
POST /v1/{workspace_id}/simulations/cases/{case_id}/run HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 297

{
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "max_turns": 20,
  "concurrency": 1,
  "branch_name": "text",
  "tags": [
    "text"
  ],
  "exploration": {
    "coverage_driven_selection": false,
    "enable_forking": false,
    "max_forks_per_scenario": 2,
    "recommend_candidates": 3
  }
}
{
  "run_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "running",
  "scenarios": [
    {
      "description": "text",
      "temperament": "neutral",
      "initial_message": "text",
      "scenario_instructions": "text",
      "persona": {
        "name": "",
        "role": "patient",
        "communication_style": "",
        "default_language": "en-US",
        "background": ""
      },
      "case_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "case_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "inferred_target_spec": {
    "desired_states": [
      "text"
    ],
    "non_desired_states": [
      {
        "state": "text",
        "mode": "hard"
      }
    ],
    "ordered_pathways": [
      {
        "id": "text",
        "sequence": [
          "text"
        ]
      }
    ],
    "completion_criteria": {
      "state_based": [
        "text"
      ],
      "tool_based": [
        "text"
      ]
    }
  },
  "inferred_target_spec_rationale": "text"
}

Simulation Bridge Plan

post

Infer a TargetSpec from an NL objective — preview before running /bridge.

UX: user types "test scheduling failures in 20 different ways", we return a structured target_spec + rationale. The frontend shows both, lets the user edit (add/remove states, tighten pathways), then POSTs the final spec to /bridge. Same LLM, same Vertex cost structure as /bridge, but no run is created — pure inference.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Body
service_idstring · uuidRequired
objectivestring · min: 1 · max: 2000Required
Responses
200

Successful Response

application/json
rationalestring · max: 1000Required
available_statesstring[] · max: 200Optional
available_toolsstring[] · max: 200Optional
post/v1/{workspace_id}/simulations/bridge/plan
POST /v1/{workspace_id}/simulations/bridge/plan HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 72

{
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "objective": "text"
}
{
  "target_spec": {
    "desired_states": [
      "text"
    ],
    "non_desired_states": [
      {
        "state": "text",
        "mode": "hard"
      }
    ],
    "ordered_pathways": [
      {
        "id": "text",
        "sequence": [
          "text"
        ]
      }
    ],
    "completion_criteria": {
      "state_based": [
        "text"
      ],
      "tool_based": [
        "text"
      ]
    }
  },
  "rationale": "text",
  "available_states": [
    "text"
  ],
  "available_tools": [
    "text"
  ]
}
PreviousComplianceNextInsights

Last updated

Was this helpful?