# Simulations

## GET /v1/{workspace\_id}/simulations/runs

> List Simulation Runs

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/runs":{"get":{"tags":["Simulations"],"summary":"List Simulation Runs","operationId":"list-simulation-runs","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"service_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List-Simulation-Runs"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create Simulation Run

> Create a simulation coverage run with an optional Lakebase branch.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"CreateRunRequest":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"},"branch_name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Branch Name"},"tags":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Tags"}},"type":"object","required":["service_id"],"title":"CreateRunRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/runs":{"post":{"tags":["Simulations"],"summary":"Create Simulation Run","description":"Create a simulation coverage run with an optional Lakebase branch.","operationId":"create-simulation-run","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRunRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create-Simulation-Run"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## List Simulation Suites

> List runnable simulation suites derived from \`suite:\*\` case tags.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"ListSimulationSuitesResponse":{"properties":{"suites":{"items":{"$ref":"#/components/schemas/SimulationSuiteResponse"},"type":"array","title":"Suites"}},"type":"object","required":["suites"],"title":"ListSimulationSuitesResponse"},"SimulationSuiteResponse":{"properties":{"tag":{"type":"string","maxLength":128,"title":"Tag"},"name":{"type":"string","maxLength":128,"title":"Name"},"case_count":{"type":"integer","minimum":0,"title":"Case Count"},"service_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Service Ids"},"latest_updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Latest Updated At"}},"type":"object","required":["tag","name","case_count"],"title":"SimulationSuiteResponse","description":"A runnable suite derived from persisted `suite:*` case tags."}}},"paths":{"/v1/{workspace_id}/simulations/suites":{"get":{"tags":["Simulations"],"summary":"List Simulation Suites","description":"List runnable simulation suites derived from `suite:*` case tags.","operationId":"list-simulation-suites","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSimulationSuitesResponse"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## List Simulation Cases

> List durable simulation cases for case-library inspection.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"PaginatedResponse_SimulationCaseResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SimulationCaseResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[SimulationCaseResponse]"},"SimulationCaseResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"description":{"type":"string","maxLength":2000,"title":"Description"},"scenario_instructions":{"type":"string","maxLength":10000,"title":"Scenario Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message"},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"},"fixtures":{"additionalProperties":true,"type":"object","title":"Fixtures"},"constraints":{"additionalProperties":true,"type":"object","title":"Constraints"},"target_spec":{"additionalProperties":true,"type":"object","title":"Target Spec"},"assertions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Assertions"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"provenance":{"type":"string","maxLength":64,"title":"Provenance","default":"manual"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","description","scenario_instructions","initial_message"],"title":"SimulationCaseResponse","description":"HTTP response shape for durable simulation cases."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/cases":{"get":{"tags":["Simulations"],"summary":"List Simulation Cases","description":"List durable simulation cases for case-library inspection.","operationId":"list-simulation-cases","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"service_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"}},{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":128},"maxItems":20},{"type":"null"}],"title":"Tags"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"exclusiveMinimum":0,"default":10,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Continuation Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_SimulationCaseResponse_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create Simulation Cases

> Create durable simulation cases for an internal benchmark suite.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"CreateSimulationCasesRequest":{"properties":{"cases":{"items":{"$ref":"#/components/schemas/CreateSimulationCaseItem"},"type":"array","maxItems":100,"minItems":1,"title":"Cases"}},"type":"object","required":["cases"],"title":"CreateSimulationCasesRequest"},"CreateSimulationCaseItem":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"description":{"type":"string","maxLength":2000,"minLength":1,"title":"Description"},"scenario_instructions":{"type":"string","maxLength":10000,"minLength":1,"title":"Scenario Instructions"},"initial_message":{"type":"string","maxLength":2000,"minLength":1,"title":"Initial Message"},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"},"fixtures":{"additionalProperties":true,"type":"object","title":"Fixtures"},"constraints":{"additionalProperties":true,"type":"object","title":"Constraints"},"target_spec":{"additionalProperties":true,"type":"object","title":"Target Spec"},"assertions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":100,"title":"Assertions"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Tags"},"provenance":{"type":"string","maxLength":64,"title":"Provenance","default":"manual"}},"type":"object","required":["description","scenario_instructions","initial_message"],"title":"CreateSimulationCaseItem","description":"One durable simulation case to create."},"CreateSimulationCasesResponse":{"properties":{"cases":{"items":{"$ref":"#/components/schemas/SimulationCaseResponse"},"type":"array","title":"Cases"}},"type":"object","required":["cases"],"title":"CreateSimulationCasesResponse"},"SimulationCaseResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"description":{"type":"string","maxLength":2000,"title":"Description"},"scenario_instructions":{"type":"string","maxLength":10000,"title":"Scenario Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message"},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"},"fixtures":{"additionalProperties":true,"type":"object","title":"Fixtures"},"constraints":{"additionalProperties":true,"type":"object","title":"Constraints"},"target_spec":{"additionalProperties":true,"type":"object","title":"Target Spec"},"assertions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Assertions"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"provenance":{"type":"string","maxLength":64,"title":"Provenance","default":"manual"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","description","scenario_instructions","initial_message"],"title":"SimulationCaseResponse","description":"HTTP response shape for durable simulation cases."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/cases":{"post":{"tags":["Simulations"],"summary":"Create Simulation Cases","description":"Create durable simulation cases for an internal benchmark suite.","operationId":"create-simulation-cases","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSimulationCasesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSimulationCasesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Get Simulation Case

> Fetch one durable simulation case for case-library inspection.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SimulationCaseResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"description":{"type":"string","maxLength":2000,"title":"Description"},"scenario_instructions":{"type":"string","maxLength":10000,"title":"Scenario Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message"},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"},"fixtures":{"additionalProperties":true,"type":"object","title":"Fixtures"},"constraints":{"additionalProperties":true,"type":"object","title":"Constraints"},"target_spec":{"additionalProperties":true,"type":"object","title":"Target Spec"},"assertions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Assertions"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"provenance":{"type":"string","maxLength":64,"title":"Provenance","default":"manual"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","description","scenario_instructions","initial_message"],"title":"SimulationCaseResponse","description":"HTTP response shape for durable simulation cases."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/cases/{case_id}":{"get":{"tags":["Simulations"],"summary":"Get Simulation Case","description":"Fetch one durable simulation case for case-library inspection.","operationId":"get-simulation-case","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Case Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationCaseResponse"}}}},"404":{"description":"Simulation case not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Delete Simulation Case

> Delete one durable simulation case.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/cases/{case_id}":{"delete":{"tags":["Simulations"],"summary":"Delete Simulation Case","description":"Delete one durable simulation case.","operationId":"delete-simulation-case","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Case Id"}}],"responses":{"204":{"description":"Successful Response"},"404":{"description":"Simulation case not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update Simulation Case

> Update editable fields on one durable simulation case.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"UpdateSimulationCaseRequest":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"persona":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Persona"},"description":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Description"},"scenario_instructions":{"anyOf":[{"type":"string","maxLength":10000,"minLength":1},{"type":"null"}],"title":"Scenario Instructions"},"initial_message":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Initial Message"},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"},"fixtures":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Fixtures"},"constraints":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Constraints"},"target_spec":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Target Spec"},"assertions":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array","maxItems":100},{"type":"null"}],"title":"Assertions"},"tags":{"anyOf":[{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20},{"type":"null"}],"title":"Tags"},"provenance":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Provenance"}},"type":"object","title":"UpdateSimulationCaseRequest","description":"Partial update for one durable simulation case."},"SimulationCaseResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"description":{"type":"string","maxLength":2000,"title":"Description"},"scenario_instructions":{"type":"string","maxLength":10000,"title":"Scenario Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message"},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"},"fixtures":{"additionalProperties":true,"type":"object","title":"Fixtures"},"constraints":{"additionalProperties":true,"type":"object","title":"Constraints"},"target_spec":{"additionalProperties":true,"type":"object","title":"Target Spec"},"assertions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Assertions"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"provenance":{"type":"string","maxLength":64,"title":"Provenance","default":"manual"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","workspace_id","description","scenario_instructions","initial_message"],"title":"SimulationCaseResponse","description":"HTTP response shape for durable simulation cases."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/cases/{case_id}":{"patch":{"tags":["Simulations"],"summary":"Update Simulation Case","description":"Update editable fields on one durable simulation case.","operationId":"update-simulation-case","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Case Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSimulationCaseRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationCaseResponse"}}}},"404":{"description":"Simulation case not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Simulation Run

> Fetch a single run including objective / bridge\_request / scenarios.\
> \
> Use the bridge\_request payload to re-POST /bridge and replay the run.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SimulationRunResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"branch_name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Branch Name"},"status":{"type":"string","enum":["running","completed","failed"],"title":"Status"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"total_sessions":{"type":"integer","title":"Total Sessions","default":0},"total_turns":{"type":"integer","title":"Total Turns","default":0},"objective":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Objective"},"bridge_request":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Bridge Request"},"scenarios":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Scenarios"},"snapshot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Snapshot"},"total_scenarios_requested":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Scenarios Requested"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"metric_status":{"type":"string","enum":["pending","available","unavailable"],"title":"Metric Status","default":"pending"},"metric_result_count":{"type":"integer","title":"Metric Result Count","default":0},"metrics_last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Metrics Last Checked At"}},"type":"object","required":["id","service_id","status"],"title":"SimulationRunResponse","description":"Full run payload — used by GET /runs/{run_id} for replay flows."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/runs/{run_id}":{"get":{"tags":["Simulations"],"summary":"Get Simulation Run","description":"Fetch a single run including objective / bridge_request / scenarios.\n\nUse the bridge_request payload to re-POST /bridge and replay the run.","operationId":"get-simulation-run","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationRunResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## POST /v1/{workspace\_id}/simulations/runs/{run\_id}/complete

> Complete Simulation Run

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/runs/{run_id}/complete":{"post":{"tags":["Simulations"],"summary":"Complete Simulation Run","operationId":"complete-simulation-run","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}},{"name":"error","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"},"title":"Response Complete-Simulation-Run"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create Simulation Session

> 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.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"src__routes__simulations__CreateSessionRequest":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"},"branch_name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Branch Name"},"tags":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Tags"},"caller_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Caller Id","description":"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_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"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)."}},"type":"object","required":["service_id"],"title":"CreateSessionRequest"},"SimulationSessionResponse":{"properties":{"session_id":{"type":"string","title":"Session Id"},"greeting":{"type":"string","title":"Greeting"},"is_terminal":{"type":"boolean","title":"Is Terminal"},"snapshot":{"$ref":"#/components/schemas/SimulationSnapshotResponse"}},"type":"object","required":["session_id","greeting","is_terminal","snapshot"],"title":"SimulationSessionResponse"},"SimulationSnapshotResponse":{"properties":{"current_state":{"$ref":"#/components/schemas/SimulationStateResponse"},"reachable_states":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Reachable States","default":[]},"turn_policy":{"$ref":"#/components/schemas/SimulationTurnPolicyResponse","default":{"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":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Conversation History","default":[]},"states_visited":{"items":{"type":"string"},"type":"array","title":"States Visited","default":[]},"state_transitions":{"items":{"items":{"type":"string"},"type":"array"},"type":"array","title":"State Transitions","default":[]},"total_turns":{"type":"integer","title":"Total Turns","default":0},"tools_called":{"items":{"type":"string"},"type":"array","title":"Tools Called","default":[]},"terminal_reached":{"type":"boolean","title":"Terminal Reached","default":false},"context_graph_topology":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Context Graph Topology","default":[]},"terminal_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Terminal State"}},"additionalProperties":true,"type":"object","required":["current_state"],"title":"SimulationSnapshotResponse"},"SimulationStateResponse":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"objective":{"type":"string","title":"Objective","default":""},"actions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Actions","default":[]},"exit_conditions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Exit Conditions","default":[]},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints","default":[]},"guardrails":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Guardrails","default":[]},"tools":{"items":{"type":"string"},"type":"array","title":"Tools","default":[]}},"additionalProperties":true,"type":"object","required":["name","type"],"title":"SimulationStateResponse"},"SimulationTurnPolicyResponse":{"properties":{"barge_in_enabled":{"type":"boolean","title":"Barge In Enabled","default":true},"greeting_shield_s":{"type":"number","title":"Greeting Shield S","default":0},"safety_response":{"type":"string","title":"Safety Response","default":"suspend_forward"},"context_strategy":{"type":"string","title":"Context Strategy","default":"full"},"block_forward_call":{"type":"boolean","title":"Block Forward Call","default":false},"block_forward_call_after_turns":{"type":"integer","title":"Block Forward Call After Turns","default":-1}},"type":"object","title":"SimulationTurnPolicyResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/runs/{run_id}/sessions":{"post":{"tags":["Simulations"],"summary":"Create Simulation Session","description":"Create a simulation session within a run. Proxies to agent-engine.\n\nentity_id ownership: agent-engine's _resolve_caller queries the entity\nwith workspace_id scoping — a workspace-A entity_id resolves to None in\nworkspace-B, so no cross-tenant data is exposed.","operationId":"create-simulation-session","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__routes__simulations__CreateSessionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationSessionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Simulation Step

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"StepRequest":{"properties":{"session_id":{"type":"string","maxLength":64,"title":"Session Id"},"caller_text":{"type":"string","maxLength":2000,"title":"Caller Text"},"emotion":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Emotion"},"valence":{"anyOf":[{"type":"number","maximum":1,"minimum":-1},{"type":"null"}],"title":"Valence"}},"type":"object","required":["session_id","caller_text"],"title":"StepRequest"},"SimulationStepResponse":{"properties":{"observation":{"$ref":"#/components/schemas/SimulationObservation"},"snapshot":{"$ref":"#/components/schemas/SimulationSnapshotResponse"}},"type":"object","required":["observation","snapshot"],"title":"SimulationStepResponse"},"SimulationObservation":{"properties":{"state_before":{"type":"string","title":"State Before"},"state_after":{"type":"string","title":"State After"},"state_changed":{"type":"boolean","title":"State Changed"},"agent_text":{"type":"string","title":"Agent Text"},"is_terminal":{"type":"boolean","title":"Is Terminal"},"tools_called":{"items":{"type":"string"},"type":"array","title":"Tools Called","default":[]},"tool_call_details":{"items":{"$ref":"#/components/schemas/ToolCallDetail"},"type":"array","title":"Tool Call Details","default":[]},"selected_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Action"},"empathy_tier":{"type":"integer","title":"Empathy Tier","default":0},"has_pause":{"type":"boolean","title":"Has Pause","default":false},"engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Engine Ms"},"nav_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nav Ms"}},"type":"object","required":["state_before","state_after","state_changed","agent_text","is_terminal"],"title":"SimulationObservation"},"ToolCallDetail":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"input":{"type":"string","title":"Input","default":""},"result":{"type":"string","title":"Result","default":""},"call_id":{"type":"string","title":"Call Id","default":""},"succeeded":{"type":"boolean","title":"Succeeded","default":true}},"type":"object","required":["tool_name"],"title":"ToolCallDetail","description":"Rich tool call data from a simulation step."},"SimulationSnapshotResponse":{"properties":{"current_state":{"$ref":"#/components/schemas/SimulationStateResponse"},"reachable_states":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Reachable States","default":[]},"turn_policy":{"$ref":"#/components/schemas/SimulationTurnPolicyResponse","default":{"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":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Conversation History","default":[]},"states_visited":{"items":{"type":"string"},"type":"array","title":"States Visited","default":[]},"state_transitions":{"items":{"items":{"type":"string"},"type":"array"},"type":"array","title":"State Transitions","default":[]},"total_turns":{"type":"integer","title":"Total Turns","default":0},"tools_called":{"items":{"type":"string"},"type":"array","title":"Tools Called","default":[]},"terminal_reached":{"type":"boolean","title":"Terminal Reached","default":false},"context_graph_topology":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Context Graph Topology","default":[]},"terminal_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Terminal State"}},"additionalProperties":true,"type":"object","required":["current_state"],"title":"SimulationSnapshotResponse"},"SimulationStateResponse":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"objective":{"type":"string","title":"Objective","default":""},"actions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Actions","default":[]},"exit_conditions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Exit Conditions","default":[]},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints","default":[]},"guardrails":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Guardrails","default":[]},"tools":{"items":{"type":"string"},"type":"array","title":"Tools","default":[]}},"additionalProperties":true,"type":"object","required":["name","type"],"title":"SimulationStateResponse"},"SimulationTurnPolicyResponse":{"properties":{"barge_in_enabled":{"type":"boolean","title":"Barge In Enabled","default":true},"greeting_shield_s":{"type":"number","title":"Greeting Shield S","default":0},"safety_response":{"type":"string","title":"Safety Response","default":"suspend_forward"},"context_strategy":{"type":"string","title":"Context Strategy","default":"full"},"block_forward_call":{"type":"boolean","title":"Block Forward Call","default":false},"block_forward_call_after_turns":{"type":"integer","title":"Block Forward Call After Turns","default":-1}},"type":"object","title":"SimulationTurnPolicyResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/sessions/{session_id}/step":{"post":{"tags":["Simulations"],"summary":"Simulation Step","description":"Step a simulation session and auto-store the turn observation.","operationId":"simulation-step","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StepRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationStepResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Simulation Fork

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"ForkRequest":{"properties":{"alternatives":{"items":{"$ref":"#/components/schemas/ForkAlternative"},"type":"array","maxItems":20,"minItems":1,"title":"Alternatives"}},"type":"object","required":["alternatives"],"title":"ForkRequest"},"ForkAlternative":{"properties":{"caller_text":{"type":"string","maxLength":2000,"title":"Caller Text"},"emotion":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Emotion"},"valence":{"anyOf":[{"type":"number","maximum":1,"minimum":-1},{"type":"null"}],"title":"Valence"}},"type":"object","required":["caller_text"],"title":"ForkAlternative"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/sessions/{session_id}/fork":{"post":{"tags":["Simulations"],"summary":"Simulation Fork","description":"Fork a session into N branches — clone + step each alternative atomically.","operationId":"simulation-fork","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForkRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Simulation-Fork"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Score Simulation Session

> ASI assigns a score to a completed simulation session.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"ScoreSessionRequest":{"properties":{"score":{"type":"number","maximum":100,"minimum":0,"title":"Score"},"score_rationale":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Score Rationale"}},"type":"object","required":["score"],"title":"ScoreSessionRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/sessions/{session_id}/score":{"post":{"tags":["Simulations"],"summary":"Score Simulation Session","description":"ASI assigns a score to a completed simulation session.","operationId":"score-simulation-session","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreSessionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"},"title":"Response Score-Simulation-Session"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create Test Conversation

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"src__routes__simulations__CreateSessionRequest":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"},"branch_name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Branch Name"},"tags":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Tags"},"caller_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Caller Id","description":"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_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"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)."}},"type":"object","required":["service_id"],"title":"CreateSessionRequest"},"SimulationSessionResponse":{"properties":{"session_id":{"type":"string","title":"Session Id"},"greeting":{"type":"string","title":"Greeting"},"is_terminal":{"type":"boolean","title":"Is Terminal"},"snapshot":{"$ref":"#/components/schemas/SimulationSnapshotResponse"}},"type":"object","required":["session_id","greeting","is_terminal","snapshot"],"title":"SimulationSessionResponse"},"SimulationSnapshotResponse":{"properties":{"current_state":{"$ref":"#/components/schemas/SimulationStateResponse"},"reachable_states":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Reachable States","default":[]},"turn_policy":{"$ref":"#/components/schemas/SimulationTurnPolicyResponse","default":{"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":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Conversation History","default":[]},"states_visited":{"items":{"type":"string"},"type":"array","title":"States Visited","default":[]},"state_transitions":{"items":{"items":{"type":"string"},"type":"array"},"type":"array","title":"State Transitions","default":[]},"total_turns":{"type":"integer","title":"Total Turns","default":0},"tools_called":{"items":{"type":"string"},"type":"array","title":"Tools Called","default":[]},"terminal_reached":{"type":"boolean","title":"Terminal Reached","default":false},"context_graph_topology":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Context Graph Topology","default":[]},"terminal_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Terminal State"}},"additionalProperties":true,"type":"object","required":["current_state"],"title":"SimulationSnapshotResponse"},"SimulationStateResponse":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"objective":{"type":"string","title":"Objective","default":""},"actions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Actions","default":[]},"exit_conditions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Exit Conditions","default":[]},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints","default":[]},"guardrails":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Guardrails","default":[]},"tools":{"items":{"type":"string"},"type":"array","title":"Tools","default":[]}},"additionalProperties":true,"type":"object","required":["name","type"],"title":"SimulationStateResponse"},"SimulationTurnPolicyResponse":{"properties":{"barge_in_enabled":{"type":"boolean","title":"Barge In Enabled","default":true},"greeting_shield_s":{"type":"number","title":"Greeting Shield S","default":0},"safety_response":{"type":"string","title":"Safety Response","default":"suspend_forward"},"context_strategy":{"type":"string","title":"Context Strategy","default":"full"},"block_forward_call":{"type":"boolean","title":"Block Forward Call","default":false},"block_forward_call_after_turns":{"type":"integer","title":"Block Forward Call After Turns","default":-1}},"type":"object","title":"SimulationTurnPolicyResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/sessions":{"post":{"tags":["Simulations"],"summary":"Create Test Conversation","description":"Create a test conversation session (no coverage run required).","operationId":"create-test-conversation","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__routes__simulations__CreateSessionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationSessionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Test Conversation Step

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"StepRequest":{"properties":{"session_id":{"type":"string","maxLength":64,"title":"Session Id"},"caller_text":{"type":"string","maxLength":2000,"title":"Caller Text"},"emotion":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Emotion"},"valence":{"anyOf":[{"type":"number","maximum":1,"minimum":-1},{"type":"null"}],"title":"Valence"}},"type":"object","required":["session_id","caller_text"],"title":"StepRequest"},"SimulationStepResponse":{"properties":{"observation":{"$ref":"#/components/schemas/SimulationObservation"},"snapshot":{"$ref":"#/components/schemas/SimulationSnapshotResponse"}},"type":"object","required":["observation","snapshot"],"title":"SimulationStepResponse"},"SimulationObservation":{"properties":{"state_before":{"type":"string","title":"State Before"},"state_after":{"type":"string","title":"State After"},"state_changed":{"type":"boolean","title":"State Changed"},"agent_text":{"type":"string","title":"Agent Text"},"is_terminal":{"type":"boolean","title":"Is Terminal"},"tools_called":{"items":{"type":"string"},"type":"array","title":"Tools Called","default":[]},"tool_call_details":{"items":{"$ref":"#/components/schemas/ToolCallDetail"},"type":"array","title":"Tool Call Details","default":[]},"selected_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Action"},"empathy_tier":{"type":"integer","title":"Empathy Tier","default":0},"has_pause":{"type":"boolean","title":"Has Pause","default":false},"engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Engine Ms"},"nav_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nav Ms"}},"type":"object","required":["state_before","state_after","state_changed","agent_text","is_terminal"],"title":"SimulationObservation"},"ToolCallDetail":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"input":{"type":"string","title":"Input","default":""},"result":{"type":"string","title":"Result","default":""},"call_id":{"type":"string","title":"Call Id","default":""},"succeeded":{"type":"boolean","title":"Succeeded","default":true}},"type":"object","required":["tool_name"],"title":"ToolCallDetail","description":"Rich tool call data from a simulation step."},"SimulationSnapshotResponse":{"properties":{"current_state":{"$ref":"#/components/schemas/SimulationStateResponse"},"reachable_states":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Reachable States","default":[]},"turn_policy":{"$ref":"#/components/schemas/SimulationTurnPolicyResponse","default":{"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":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Conversation History","default":[]},"states_visited":{"items":{"type":"string"},"type":"array","title":"States Visited","default":[]},"state_transitions":{"items":{"items":{"type":"string"},"type":"array"},"type":"array","title":"State Transitions","default":[]},"total_turns":{"type":"integer","title":"Total Turns","default":0},"tools_called":{"items":{"type":"string"},"type":"array","title":"Tools Called","default":[]},"terminal_reached":{"type":"boolean","title":"Terminal Reached","default":false},"context_graph_topology":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Context Graph Topology","default":[]},"terminal_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Terminal State"}},"additionalProperties":true,"type":"object","required":["current_state"],"title":"SimulationSnapshotResponse"},"SimulationStateResponse":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"objective":{"type":"string","title":"Objective","default":""},"actions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Actions","default":[]},"exit_conditions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Exit Conditions","default":[]},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints","default":[]},"guardrails":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Guardrails","default":[]},"tools":{"items":{"type":"string"},"type":"array","title":"Tools","default":[]}},"additionalProperties":true,"type":"object","required":["name","type"],"title":"SimulationStateResponse"},"SimulationTurnPolicyResponse":{"properties":{"barge_in_enabled":{"type":"boolean","title":"Barge In Enabled","default":true},"greeting_shield_s":{"type":"number","title":"Greeting Shield S","default":0},"safety_response":{"type":"string","title":"Safety Response","default":"suspend_forward"},"context_strategy":{"type":"string","title":"Context Strategy","default":"full"},"block_forward_call":{"type":"boolean","title":"Block Forward Call","default":false},"block_forward_call_after_turns":{"type":"integer","title":"Block Forward Call After Turns","default":-1}},"type":"object","title":"SimulationTurnPolicyResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/sessions/step":{"post":{"tags":["Simulations"],"summary":"Test Conversation Step","description":"Step a test conversation (no coverage auto-store).","operationId":"test-conversation-step","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StepRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationStepResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## POST /v1/{workspace\_id}/simulations/sessions/recommend

> Simulation Recommend

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RecommendRequest":{"properties":{"session_id":{"type":"string","maxLength":64,"title":"Session Id"},"n":{"type":"integer","maximum":20,"minimum":1,"title":"N","default":5}},"type":"object","required":["session_id"],"title":"RecommendRequest"},"RecommendResponse":{"properties":{"suggestions":{"items":{"type":"string"},"type":"array","maxItems":100,"title":"Suggestions","description":"LLM-generated caller message suggestions"}},"type":"object","required":["suggestions"],"title":"RecommendResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/sessions/recommend":{"post":{"tags":["Simulations"],"summary":"Simulation Recommend","operationId":"simulation-recommend","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## GET /v1/{workspace\_id}/simulations/sessions/{session\_id}

> Simulation Observe

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SimulationSnapshotResponse":{"properties":{"current_state":{"$ref":"#/components/schemas/SimulationStateResponse"},"reachable_states":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Reachable States","default":[]},"turn_policy":{"$ref":"#/components/schemas/SimulationTurnPolicyResponse","default":{"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":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Conversation History","default":[]},"states_visited":{"items":{"type":"string"},"type":"array","title":"States Visited","default":[]},"state_transitions":{"items":{"items":{"type":"string"},"type":"array"},"type":"array","title":"State Transitions","default":[]},"total_turns":{"type":"integer","title":"Total Turns","default":0},"tools_called":{"items":{"type":"string"},"type":"array","title":"Tools Called","default":[]},"terminal_reached":{"type":"boolean","title":"Terminal Reached","default":false},"context_graph_topology":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Context Graph Topology","default":[]},"terminal_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Terminal State"}},"additionalProperties":true,"type":"object","required":["current_state"],"title":"SimulationSnapshotResponse"},"SimulationStateResponse":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"objective":{"type":"string","title":"Objective","default":""},"actions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Actions","default":[]},"exit_conditions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Exit Conditions","default":[]},"action_guidelines":{"items":{"type":"string"},"type":"array","title":"Action Guidelines","default":[]},"boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Boundary Constraints","default":[]},"guardrails":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Guardrails","default":[]},"tools":{"items":{"type":"string"},"type":"array","title":"Tools","default":[]}},"additionalProperties":true,"type":"object","required":["name","type"],"title":"SimulationStateResponse"},"SimulationTurnPolicyResponse":{"properties":{"barge_in_enabled":{"type":"boolean","title":"Barge In Enabled","default":true},"greeting_shield_s":{"type":"number","title":"Greeting Shield S","default":0},"safety_response":{"type":"string","title":"Safety Response","default":"suspend_forward"},"context_strategy":{"type":"string","title":"Context Strategy","default":"full"},"block_forward_call":{"type":"boolean","title":"Block Forward Call","default":false},"block_forward_call_after_turns":{"type":"integer","title":"Block Forward Call After Turns","default":-1}},"type":"object","title":"SimulationTurnPolicyResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/sessions/{session_id}":{"get":{"tags":["Simulations"],"summary":"Simulation Observe","operationId":"simulation-observe","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationSnapshotResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## DELETE /v1/{workspace\_id}/simulations/sessions/{session\_id}

> Simulation Destroy

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"DestroySessionResponse":{"properties":{"status":{"type":"string","const":"destroyed","title":"Status","description":"Session destruction status"}},"type":"object","required":["status"],"title":"DestroySessionResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/sessions/{session_id}":{"delete":{"tags":["Simulations"],"summary":"Simulation Destroy","operationId":"simulation-destroy","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestroySessionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /v1/{workspace\_id}/simulations/sessions/{session\_id}/intelligence

> Simulation Intelligence

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SimulationIntelligenceResponse":{"properties":{"session_id":{"type":"string","title":"Session Id"},"intelligence":{"additionalProperties":true,"type":"object","title":"Intelligence"}},"type":"object","required":["session_id","intelligence"],"title":"SimulationIntelligenceResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/sessions/{session_id}/intelligence":{"get":{"tags":["Simulations"],"summary":"Simulation Intelligence","operationId":"simulation-intelligence","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationIntelligenceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Simulation Coverage Graph

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/services/{service_id}/graph":{"get":{"tags":["Simulations"],"summary":"Get Simulation Coverage Graph","description":"Get the B&B knowledge graph for a service — topology + observations merged.","operationId":"get-simulation-coverage-graph","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"service_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Service Id"}},{"name":"run_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"}},{"name":"include_turns","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Turns"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get-Simulation-Coverage-Graph"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## DELETE /v1/{workspace\_id}/simulations/services/{service\_id}/graph

> Delete Simulation Coverage Graph

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/services/{service_id}/graph":{"delete":{"tags":["Simulations"],"summary":"Delete Simulation Coverage Graph","operationId":"delete-simulation-coverage-graph","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"service_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Service Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete-Simulation-Coverage-Graph"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Simulation Coverage Paths

> Get distinct trajectories from simulation sessions.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/services/{service_id}/graph/paths":{"get":{"tags":["Simulations"],"summary":"Get Simulation Coverage Paths","description":"Get distinct trajectories from simulation sessions.","operationId":"get-simulation-coverage-paths","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"service_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Service Id"}},{"name":"run_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get-Simulation-Coverage-Paths"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /v1/{workspace\_id}/simulations/services/{service\_id}/sessions

> List Simulation Sessions

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/services/{service_id}/sessions":{"get":{"tags":["Simulations"],"summary":"List Simulation Sessions","operationId":"list-simulation-sessions","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"service_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Service Id"}},{"name":"run_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List-Simulation-Sessions"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /v1/{workspace\_id}/simulations/sessions/{session\_id}/turns

> Get Simulation Session Turns

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/sessions/{session_id}/turns":{"get":{"tags":["Simulations"],"summary":"Get Simulation Session Turns","operationId":"get-simulation-session-turns","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get-Simulation-Session-Turns"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /v1/{workspace\_id}/simulations/services/{service\_id}/turns

> Query Simulation Turns

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/services/{service_id}/turns":{"get":{"tags":["Simulations"],"summary":"Query Simulation Turns","operationId":"query-simulation-turns","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"service_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Service Id"}},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"}},{"name":"from_state","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From State"}},{"name":"to_state","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To State"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Query-Simulation-Turns"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## POST /v1/{workspace\_id}/simulations/config-to-policy

> Config To Turn Policy

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"ConfigToPolicyRequest":{"properties":{"config":{"additionalProperties":true,"type":"object","title":"Config"}},"type":"object","required":["config"],"title":"ConfigToPolicyRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/config-to-policy":{"post":{"tags":["Simulations"],"summary":"Config To Turn Policy","operationId":"config-to-turn-policy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigToPolicyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Config-To-Turn-Policy"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Simulation Bridge

> 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.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"BridgeRequest":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"},"objective":{"type":"string","maxLength":2000,"minLength":1,"title":"Objective"},"num_scenarios":{"type":"integer","maximum":50,"minimum":1,"title":"Num Scenarios","default":5},"max_turns":{"type":"integer","maximum":40,"minimum":1,"title":"Max Turns","default":20},"concurrency":{"type":"integer","maximum":20,"minimum":1,"title":"Concurrency","default":3},"branch_name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Branch Name"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"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."},"tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Tags"},"target_spec":{"anyOf":[{"$ref":"#/components/schemas/TargetSpec"},{"type":"null"}]},"exploration":{"anyOf":[{"$ref":"#/components/schemas/ExplorationConfig"},{"type":"null"}]},"auto_target_spec":{"type":"boolean","title":"Auto Target Spec","default":false},"async_generation":{"type":"boolean","title":"Async Generation","default":false}},"type":"object","required":["service_id","objective"],"title":"BridgeRequest"},"TargetSpec":{"properties":{"desired_states":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"Desired States"},"non_desired_states":{"items":{"$ref":"#/components/schemas/NonDesiredState"},"type":"array","maxItems":50,"title":"Non Desired States"},"ordered_pathways":{"items":{"$ref":"#/components/schemas/OrderedPathway"},"type":"array","maxItems":20,"title":"Ordered Pathways"},"completion_criteria":{"$ref":"#/components/schemas/CompletionCriteria"}},"type":"object","title":"TargetSpec"},"NonDesiredState":{"properties":{"state":{"type":"string","maxLength":128,"title":"State"},"mode":{"type":"string","enum":["hard","soft"],"title":"Mode","default":"hard"}},"type":"object","required":["state"],"title":"NonDesiredState"},"OrderedPathway":{"properties":{"id":{"type":"string","maxLength":64,"title":"Id"},"sequence":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"minItems":1,"title":"Sequence"}},"type":"object","required":["id","sequence"],"title":"OrderedPathway"},"CompletionCriteria":{"properties":{"state_based":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"State Based"},"tool_based":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"Tool Based"}},"type":"object","title":"CompletionCriteria"},"ExplorationConfig":{"properties":{"coverage_driven_selection":{"type":"boolean","title":"Coverage Driven Selection","default":false},"enable_forking":{"type":"boolean","title":"Enable Forking","default":false},"max_forks_per_scenario":{"type":"integer","maximum":5,"minimum":0,"title":"Max Forks Per Scenario","default":2},"recommend_candidates":{"type":"integer","maximum":10,"minimum":1,"title":"Recommend Candidates","default":3}},"type":"object","title":"ExplorationConfig"},"BridgeResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"status":{"type":"string","enum":["running","completed","failed"],"title":"Status"},"scenarios":{"items":{"$ref":"#/components/schemas/Scenario"},"type":"array","title":"Scenarios"},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"inferred_target_spec":{"anyOf":[{"$ref":"#/components/schemas/TargetSpec"},{"type":"null"}]},"inferred_target_spec_rationale":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Inferred Target Spec Rationale"}},"type":"object","required":["run_id","status","scenarios"],"title":"BridgeResponse"},"Scenario":{"properties":{"description":{"type":"string","maxLength":512,"title":"Description"},"temperament":{"type":"string","maxLength":32,"title":"Temperament","default":"neutral"},"initial_message":{"type":"string","maxLength":1000,"title":"Initial Message"},"scenario_instructions":{"type":"string","maxLength":2000,"title":"Scenario Instructions"},"persona":{"$ref":"#/components/schemas/ScenarioPersona"},"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"}},"type":"object","required":["description","initial_message","scenario_instructions"],"title":"Scenario"},"ScenarioPersona":{"properties":{"name":{"type":"string","maxLength":128,"title":"Name","default":""},"role":{"type":"string","maxLength":64,"title":"Role","default":"patient"},"communication_style":{"type":"string","maxLength":512,"title":"Communication Style","default":""},"default_language":{"type":"string","maxLength":16,"title":"Default Language","default":"en-US"},"background":{"type":"string","maxLength":2000,"title":"Background","default":""}},"type":"object","title":"ScenarioPersona"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/bridge":{"post":{"tags":["Simulations"],"summary":"Simulation Bridge","description":"NL objective to N autonomous scenarios against the tracked simulation primitives.\n\nReturns immediately with run_id + generated scenarios. Scenarios run in\nthe background via BridgeExecutor (lifecycle-managed, shutdown-drained).\nCompletion events are emitted to Delta via world_emitter for SDP\nobservability.","operationId":"simulation-bridge","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BridgeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BridgeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Run Simulation Benchmark

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RunSimulationBenchmarkRequest":{"properties":{"required_tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Required Tags"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"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_cases":{"type":"integer","maximum":200,"minimum":1,"title":"Max Cases","default":20},"max_turns":{"type":"integer","maximum":40,"minimum":1,"title":"Max Turns","default":20},"concurrency":{"type":"integer","maximum":20,"minimum":1,"title":"Concurrency","default":1},"branch_name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Branch Name"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Tags"},"exploration":{"anyOf":[{"$ref":"#/components/schemas/ExplorationConfig"},{"type":"null"}]}},"type":"object","title":"RunSimulationBenchmarkRequest"},"ExplorationConfig":{"properties":{"coverage_driven_selection":{"type":"boolean","title":"Coverage Driven Selection","default":false},"enable_forking":{"type":"boolean","title":"Enable Forking","default":false},"max_forks_per_scenario":{"type":"integer","maximum":5,"minimum":0,"title":"Max Forks Per Scenario","default":2},"recommend_candidates":{"type":"integer","maximum":10,"minimum":1,"title":"Recommend Candidates","default":3}},"type":"object","title":"ExplorationConfig"},"SimulationBenchmarkRunResponse":{"properties":{"batch_id":{"type":"string","format":"uuid","title":"Batch Id"},"required_tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Required Tags"},"selected_case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Selected Case Ids"},"run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Run Ids"},"cases":{"items":{"$ref":"#/components/schemas/SimulationBenchmarkCaseResult"},"type":"array","title":"Cases"},"skipped_cases":{"items":{"$ref":"#/components/schemas/SimulationBenchmarkCaseResult"},"type":"array","title":"Skipped Cases"},"failed_to_start_cases":{"items":{"$ref":"#/components/schemas/SimulationBenchmarkCaseResult"},"type":"array","title":"Failed To Start Cases"},"aggregate_summary":{"$ref":"#/components/schemas/SimulationBenchmarkAggregateSummary"}},"type":"object","required":["batch_id","required_tags","selected_case_ids","run_ids","cases","skipped_cases","failed_to_start_cases","aggregate_summary"],"title":"SimulationBenchmarkRunResponse"},"SimulationBenchmarkCaseResult":{"properties":{"case_id":{"type":"string","format":"uuid","title":"Case Id"},"status":{"type":"string","enum":["started","skipped","failed_to_start"],"title":"Status"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"result_pointer":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Pointer"},"reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Reason"}},"type":"object","required":["case_id","status"],"title":"SimulationBenchmarkCaseResult"},"SimulationBenchmarkAggregateSummary":{"properties":{"selected_count":{"type":"integer","title":"Selected Count"},"started_count":{"type":"integer","title":"Started Count"},"skipped_count":{"type":"integer","title":"Skipped Count"},"failed_to_start_count":{"type":"integer","title":"Failed To Start Count"},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"scored_count":{"type":"integer","title":"Scored Count","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"}},"type":"object","required":["selected_count","started_count","skipped_count","failed_to_start_count"],"title":"SimulationBenchmarkAggregateSummary"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/benchmarks/run":{"post":{"tags":["Simulations"],"summary":"Run Simulation Benchmark","description":"Run a tag-selected benchmark batch as one saved-case run per case.","operationId":"run-simulation-benchmark","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunSimulationBenchmarkRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationBenchmarkRunResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Get Simulation Benchmark Results

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"GetSimulationBenchmarkResultsRequest":{"properties":{"run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":100,"minItems":1,"title":"Run Ids"}},"type":"object","required":["run_ids"],"title":"GetSimulationBenchmarkResultsRequest"},"SimulationBenchmarkResultsResponse":{"properties":{"run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Run Ids"},"total_runs":{"type":"integer","title":"Total Runs"},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"completed_count":{"type":"integer","title":"Completed Count","default":0},"failed_count":{"type":"integer","title":"Failed Count","default":0},"scored_count":{"type":"integer","title":"Scored Count","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"},"pass_count":{"type":"integer","title":"Pass Count","default":0},"fail_count":{"type":"integer","title":"Fail Count","default":0},"metric_status":{"type":"string","enum":["pending","available","unavailable"],"title":"Metric Status","default":"pending"},"metric_result_count":{"type":"integer","title":"Metric Result Count","default":0},"metrics_last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Metrics Last Checked At"},"per_run":{"items":{"$ref":"#/components/schemas/SimulationBenchmarkPerRunSummary"},"type":"array","title":"Per Run"},"capability_breakdown":{"additionalProperties":{"$ref":"#/components/schemas/SimulationBenchmarkBreakdownSummary"},"type":"object","title":"Capability Breakdown"},"missing_run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Missing Run Ids"}},"type":"object","required":["run_ids","total_runs"],"title":"SimulationBenchmarkResultsResponse"},"SimulationBenchmarkPerRunSummary":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"status":{"type":"string","enum":["running","completed","failed"],"title":"Status"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"session_ids":{"items":{"type":"string","maxLength":128},"type":"array","title":"Session Ids"},"total_sessions":{"type":"integer","title":"Total Sessions","default":0},"total_turns":{"type":"integer","title":"Total Turns","default":0},"terminal_session_count":{"type":"integer","title":"Terminal Session Count","default":0},"scored_session_count":{"type":"integer","title":"Scored Session Count","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed"},"pass_count":{"type":"integer","title":"Pass Count","default":0},"fail_count":{"type":"integer","title":"Fail Count","default":0},"score_rationales":{"items":{"type":"string","maxLength":2000},"type":"array","title":"Score Rationales"},"capability_tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Capability Tags"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"result_pointer":{"additionalProperties":true,"type":"object","title":"Result Pointer"},"immediate_average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Immediate Average Score"},"immediate_passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Immediate Passed"},"immediate_pass_count":{"type":"integer","title":"Immediate Pass Count","default":0},"immediate_fail_count":{"type":"integer","title":"Immediate Fail Count","default":0},"metric_status":{"type":"string","enum":["pending","available","unavailable"],"title":"Metric Status","default":"pending"},"metric_result_count":{"type":"integer","title":"Metric Result Count","default":0},"metrics_last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Metrics Last Checked At"}},"type":"object","required":["run_id","service_id","status"],"title":"SimulationBenchmarkPerRunSummary"},"SimulationBenchmarkBreakdownSummary":{"properties":{"run_count":{"type":"integer","title":"Run Count","default":0},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"completed_count":{"type":"integer","title":"Completed Count","default":0},"failed_count":{"type":"integer","title":"Failed Count","default":0},"scored_count":{"type":"integer","title":"Scored Count","default":0},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"},"pass_count":{"type":"integer","title":"Pass Count","default":0},"fail_count":{"type":"integer","title":"Fail Count","default":0}},"type":"object","title":"SimulationBenchmarkBreakdownSummary"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/benchmarks/results":{"post":{"tags":["Simulations"],"summary":"Get Simulation Benchmark Results","description":"Aggregate benchmark results over the run ids returned by benchmark start.","operationId":"get-simulation-benchmark-results","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetSimulationBenchmarkResultsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationBenchmarkResultsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Run Simulation Case

> Run the current saved simulation case through the bridge executor.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RunSimulationCaseRequest":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id","description":"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_turns":{"type":"integer","maximum":40,"minimum":1,"title":"Max Turns","default":20},"concurrency":{"type":"integer","maximum":20,"minimum":1,"title":"Concurrency","default":1},"branch_name":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Branch Name"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Tags"},"exploration":{"anyOf":[{"$ref":"#/components/schemas/ExplorationConfig"},{"type":"null"}]}},"type":"object","title":"RunSimulationCaseRequest"},"ExplorationConfig":{"properties":{"coverage_driven_selection":{"type":"boolean","title":"Coverage Driven Selection","default":false},"enable_forking":{"type":"boolean","title":"Enable Forking","default":false},"max_forks_per_scenario":{"type":"integer","maximum":5,"minimum":0,"title":"Max Forks Per Scenario","default":2},"recommend_candidates":{"type":"integer","maximum":10,"minimum":1,"title":"Recommend Candidates","default":3}},"type":"object","title":"ExplorationConfig"},"BridgeResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"status":{"type":"string","enum":["running","completed","failed"],"title":"Status"},"scenarios":{"items":{"$ref":"#/components/schemas/Scenario"},"type":"array","title":"Scenarios"},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"inferred_target_spec":{"anyOf":[{"$ref":"#/components/schemas/TargetSpec"},{"type":"null"}]},"inferred_target_spec_rationale":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Inferred Target Spec Rationale"}},"type":"object","required":["run_id","status","scenarios"],"title":"BridgeResponse"},"Scenario":{"properties":{"description":{"type":"string","maxLength":512,"title":"Description"},"temperament":{"type":"string","maxLength":32,"title":"Temperament","default":"neutral"},"initial_message":{"type":"string","maxLength":1000,"title":"Initial Message"},"scenario_instructions":{"type":"string","maxLength":2000,"title":"Scenario Instructions"},"persona":{"$ref":"#/components/schemas/ScenarioPersona"},"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"}},"type":"object","required":["description","initial_message","scenario_instructions"],"title":"Scenario"},"ScenarioPersona":{"properties":{"name":{"type":"string","maxLength":128,"title":"Name","default":""},"role":{"type":"string","maxLength":64,"title":"Role","default":"patient"},"communication_style":{"type":"string","maxLength":512,"title":"Communication Style","default":""},"default_language":{"type":"string","maxLength":16,"title":"Default Language","default":"en-US"},"background":{"type":"string","maxLength":2000,"title":"Background","default":""}},"type":"object","title":"ScenarioPersona"},"TargetSpec":{"properties":{"desired_states":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"Desired States"},"non_desired_states":{"items":{"$ref":"#/components/schemas/NonDesiredState"},"type":"array","maxItems":50,"title":"Non Desired States"},"ordered_pathways":{"items":{"$ref":"#/components/schemas/OrderedPathway"},"type":"array","maxItems":20,"title":"Ordered Pathways"},"completion_criteria":{"$ref":"#/components/schemas/CompletionCriteria"}},"type":"object","title":"TargetSpec"},"NonDesiredState":{"properties":{"state":{"type":"string","maxLength":128,"title":"State"},"mode":{"type":"string","enum":["hard","soft"],"title":"Mode","default":"hard"}},"type":"object","required":["state"],"title":"NonDesiredState"},"OrderedPathway":{"properties":{"id":{"type":"string","maxLength":64,"title":"Id"},"sequence":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"minItems":1,"title":"Sequence"}},"type":"object","required":["id","sequence"],"title":"OrderedPathway"},"CompletionCriteria":{"properties":{"state_based":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"State Based"},"tool_based":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"Tool Based"}},"type":"object","title":"CompletionCriteria"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/cases/{case_id}/run":{"post":{"tags":["Simulations"],"summary":"Run Simulation Case","description":"Run the current saved simulation case through the bridge executor.","operationId":"run-simulation-case","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Case Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunSimulationCaseRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BridgeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Simulation Bridge Plan

> 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.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"BridgePlanRequest":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"},"objective":{"type":"string","maxLength":2000,"minLength":1,"title":"Objective"}},"type":"object","required":["service_id","objective"],"title":"BridgePlanRequest"},"BridgePlanResponse":{"properties":{"target_spec":{"$ref":"#/components/schemas/TargetSpec"},"rationale":{"type":"string","maxLength":1000,"title":"Rationale"},"available_states":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":200,"title":"Available States"},"available_tools":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":200,"title":"Available Tools"}},"type":"object","required":["target_spec","rationale"],"title":"BridgePlanResponse"},"TargetSpec":{"properties":{"desired_states":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"Desired States"},"non_desired_states":{"items":{"$ref":"#/components/schemas/NonDesiredState"},"type":"array","maxItems":50,"title":"Non Desired States"},"ordered_pathways":{"items":{"$ref":"#/components/schemas/OrderedPathway"},"type":"array","maxItems":20,"title":"Ordered Pathways"},"completion_criteria":{"$ref":"#/components/schemas/CompletionCriteria"}},"type":"object","title":"TargetSpec"},"NonDesiredState":{"properties":{"state":{"type":"string","maxLength":128,"title":"State"},"mode":{"type":"string","enum":["hard","soft"],"title":"Mode","default":"hard"}},"type":"object","required":["state"],"title":"NonDesiredState"},"OrderedPathway":{"properties":{"id":{"type":"string","maxLength":64,"title":"Id"},"sequence":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"minItems":1,"title":"Sequence"}},"type":"object","required":["id","sequence"],"title":"OrderedPathway"},"CompletionCriteria":{"properties":{"state_based":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"State Based"},"tool_based":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":50,"title":"Tool Based"}},"type":"object","title":"CompletionCriteria"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/simulations/bridge/plan":{"post":{"tags":["Simulations"],"summary":"Simulation Bridge Plan","description":"Infer a TargetSpec from an NL objective — preview before running /bridge.\n\nUX: user types \"test scheduling failures in 20 different ways\", we return\na structured target_spec + rationale. The frontend shows both, lets the\nuser edit (add/remove states, tighten pathways), then POSTs the final\nspec to /bridge. Same LLM, same Vertex cost structure as /bridge, but\nno run is created — pure inference.","operationId":"simulation-bridge-plan","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BridgePlanRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BridgePlanResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/api-reference/readme/platform/simulations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.