> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/api-reference/readme/platform/simulations.md).

# Simulations

## List Simulation Runs

> List simulation runs, newest first by default.\
> \
> Filters combine with AND. The list omits each run's objective, request and\
> scenarios; get-simulation-run returns them.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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":{"SimulationRunListResponse":{"properties":{"runs":{"items":{"$ref":"#/components/schemas/src__routes__simulations__SimulationRunListResponse__Item"},"type":"array","title":"Runs"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"},"total":{"type":"integer","title":"Total","description":"Runs that match the filters, across every page."}},"type":"object","required":["runs","has_more","total"],"title":"SimulationRunListResponse"},"src__routes__simulations__SimulationRunListResponse__Item":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"branch_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Branch Name"},"status":{"type":"string","enum":["running","completed","failed"],"title":"Status"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"total_sessions":{"type":"integer","title":"Total Sessions"},"total_turns":{"type":"integer","title":"Total Turns"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Failure reason saved by complete-run. Null unless status is failed, and null on\nfailed runs older than the column."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["id","service_id","branch_name","status","tags","total_sessions","total_turns","error","created_at","completed_at"],"title":"Item"},"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","description":"List simulation runs, newest first by default.\n\nFilters combine with AND. The list omits each run's objective, request and\nscenarios; get-simulation-run returns them.","operationId":"list-simulation-runs","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Page order: `-created_at` (the default, newest first) or `+created_at`.","default":[],"title":"Sort By"},"description":"Page order: `-created_at` (the default, newest first) or `+created_at`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"exclusiveMinimum":0,"default":20,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"title":"Continuation Token"}},{"name":"service_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"}},{"name":"status","in":"query","required":false,"schema":{"type":"array","items":{"enum":["running","completed","failed"],"type":"string"},"description":"Runs in any of these statuses. Repeat the parameter for more than one.","default":[],"title":"Status"},"description":"Runs in any of these statuses. Repeat the parameter for more than one."},{"name":"source","in":"query","required":false,"schema":{"type":"array","items":{"enum":["suite","case","spot_check"],"type":"string"},"description":"How the run was launched, read from its tags. `case`: a saved-case run (tagged `case`,\n`case_rerun` or `case:<id>`). `suite`: a saved-case run that also carries a `suite:<id>` or\n`benchmark` tag. `spot_check`: any other run. Repeat the parameter for more than one.","default":[],"title":"Source"},"description":"How the run was launched, read from its tags. `case`: a saved-case run (tagged `case`,\n`case_rerun` or `case:<id>`). `suite`: a saved-case run that also carries a `suite:<id>` or\n`benchmark` tag. `spot_check`: any other run. Repeat the parameter for more than one."},{"name":"case_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Runs of this saved case: runs tagged `case:<case_id>`.","title":"Case Id"},"description":"Runs of this saved case: runs tagged `case:<case_id>`."},{"name":"suite_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Runs of this suite: runs tagged `suite:<suite_id>`.","title":"Suite Id"},"description":"Runs of this suite: runs tagged `suite:<suite_id>`."},{"name":"tags","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","maxLength":128},"maxItems":20,"description":"Runs that carry every one of these tags.","default":[],"title":"Tags"},"description":"Runs that carry every one of these tags."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationRunListResponse"}}}},"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://platform.api-us.concurrence.com","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","maxLength":128},"type":"array","maxItems":20,"title":"Tags"}},"type":"object","required":["service_id"],"title":"CreateRunRequest"},"CreateSimulationRunResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"branch_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Branch Name"},"status":{"type":"string","const":"running","title":"Status"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"}},"type":"object","required":["id","workspace_id","service_id","branch_name","status","tags"],"title":"CreateSimulationRunResponse"},"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":{"$ref":"#/components/schemas/CreateSimulationRunResponse"}}}},"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 first-class simulation suites.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","maxLength":128,"title":"Name"},"description":{"type":"string","maxLength":2000,"title":"Description","default":""},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"required_tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Required Tags"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"case_count":{"type":"integer","minimum":0,"title":"Case Count"},"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","name","case_count"],"title":"SimulationSuiteResponse","description":"HTTP response shape for first-class simulation suites."}}},"paths":{"/v1/{workspace_id}/simulations/suites":{"get":{"tags":["Simulations"],"summary":"List Simulation Suites","description":"List first-class simulation suites.","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"}}]}}}}
```

## Create Simulation Suite

> Create a reusable suite definition for saved simulation cases.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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":{"CreateSimulationSuiteRequest":{"properties":{"name":{"type":"string","maxLength":128,"minLength":1,"title":"Name"},"description":{"type":"string","maxLength":2000,"title":"Description","default":""},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":500,"title":"Case Ids"},"required_tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Required Tags"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"}},"additionalProperties":false,"type":"object","required":["name"],"title":"CreateSimulationSuiteRequest"},"SimulationSuiteResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","maxLength":128,"title":"Name"},"description":{"type":"string","maxLength":2000,"title":"Description","default":""},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"required_tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Required Tags"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"case_count":{"type":"integer","minimum":0,"title":"Case Count"},"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","name","case_count"],"title":"SimulationSuiteResponse","description":"HTTP response shape for first-class simulation suites."},"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/suites":{"post":{"tags":["Simulations"],"summary":"Create Simulation Suite","description":"Create a reusable suite definition for saved simulation cases.","operationId":"create-simulation-suite","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSimulationSuiteRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationSuiteResponse"}}}},"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/suites/{suite\_id}

> Get Simulation Suite

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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":{"SimulationSuiteResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","maxLength":128,"title":"Name"},"description":{"type":"string","maxLength":2000,"title":"Description","default":""},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"required_tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Required Tags"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"case_count":{"type":"integer","minimum":0,"title":"Case Count"},"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","name","case_count"],"title":"SimulationSuiteResponse","description":"HTTP response shape for first-class simulation suites."},"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/suites/{suite_id}":{"get":{"tags":["Simulations"],"summary":"Get Simulation Suite","operationId":"get-simulation-suite","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"suite_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Suite Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationSuiteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## DELETE /v1/{workspace\_id}/simulations/suites/{suite\_id}

> Delete Simulation Suite

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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/suites/{suite_id}":{"delete":{"tags":["Simulations"],"summary":"Delete Simulation Suite","operationId":"delete-simulation-suite","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"suite_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Suite Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## PATCH /v1/{workspace\_id}/simulations/suites/{suite\_id}

> Update Simulation Suite

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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":{"UpdateSimulationSuiteRequest":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":128,"minLength":1},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"case_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":500},{"type":"null"}],"title":"Case Ids"},"required_tags":{"anyOf":[{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20},{"type":"null"}],"title":"Required Tags"},"tags":{"anyOf":[{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20},{"type":"null"}],"title":"Tags"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"additionalProperties":false,"type":"object","title":"UpdateSimulationSuiteRequest"},"SimulationSuiteResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","maxLength":128,"title":"Name"},"description":{"type":"string","maxLength":2000,"title":"Description","default":""},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"required_tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Required Tags"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"case_count":{"type":"integer","minimum":0,"title":"Case Count"},"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","name","case_count"],"title":"SimulationSuiteResponse","description":"HTTP response shape for first-class simulation suites."},"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/suites/{suite_id}":{"patch":{"tags":["Simulations"],"summary":"Update Simulation Suite","operationId":"update-simulation-suite","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"suite_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Suite Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSimulationSuiteRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationSuiteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## List Simulation Suite Runs

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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":{"ListSimulationSuiteRunsResponse":{"properties":{"suite_id":{"type":"string","format":"uuid","title":"Suite Id"},"runs":{"items":{"$ref":"#/components/schemas/SimulationSuiteRunSummary"},"type":"array","title":"Runs"}},"type":"object","required":["suite_id","runs"],"title":"ListSimulationSuiteRunsResponse"},"SimulationSuiteRunSummary":{"properties":{"suite_run_id":{"type":"string","format":"uuid","title":"Suite Run Id"},"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite Id"},"run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Run Ids"},"total_runs":{"type":"integer","title":"Total Runs"},"expected_case_count":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Expected Case Count"},"status":{"type":"string","enum":["running","completed","failed"],"title":"Status"},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"total_sessions":{"type":"integer","title":"Total Sessions","default":0},"total_turns":{"type":"integer","title":"Total Turns","default":0},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"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"}},"type":"object","required":["suite_run_id","run_ids","total_runs","status"],"title":"SimulationSuiteRunSummary"},"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/suites/{suite_id}/runs":{"get":{"tags":["Simulations"],"summary":"List Simulation Suite Runs","description":"List durable suite-run groups for a first-class suite.","operationId":"list-simulation-suite-runs","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"suite_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Suite Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSimulationSuiteRunsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## List Simulation Cases

> List durable simulation cases for case-library inspection.\
> \
> \`\`total\`\` counts every case that matches \`\`service\_id\`\`, \`\`tags\`\` and \`\`search\`\`.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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":{"SearchString":{"type":"string","maxLength":200,"minLength":1},"SimulationCaseListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SimulationCaseResponse"},"type":"array","title":"Items"},"total":{"type":"integer","minimum":0,"title":"Total","description":"Cases matching the filters and search, across every page."},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","total","has_more"],"title":"SimulationCaseListResponse"},"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"},"description":{"type":"string","maxLength":2000,"title":"Description"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"scenario":{"$ref":"#/components/schemas/SimulationCaseScenario"},"grounding":{"$ref":"#/components/schemas/SimulationCaseGrounding"},"evals":{"items":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseMetricEval"},{"$ref":"#/components/schemas/SimulationCaseAssertionEval"}]},"type":"array","title":"Evals"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"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"],"title":"SimulationCaseResponse","description":"HTTP response shape for durable simulation cases."},"SimulationCaseScenario":{"properties":{"instructions":{"type":"string","maxLength":10000,"minLength":1,"title":"Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message","default":""},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"}},"type":"object","required":["instructions"],"title":"SimulationCaseScenario","description":"Runnable patient-side scenario content for a saved case."},"SimulationCaseGrounding":{"properties":{"patient_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Patient Entity Id"}},"type":"object","title":"SimulationCaseGrounding","description":"Optional bindings that start the sim from existing workspace data."},"SimulationCaseMetricEval":{"properties":{"type":{"type":"string","const":"metric","title":"Type"},"metric_key":{"type":"string","maxLength":128,"minLength":1,"title":"Metric Key"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","metric_key"],"title":"SimulationCaseMetricEval"},"SimulationCaseAssertionEval":{"properties":{"type":{"type":"string","const":"assertion","title":"Type"},"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"assertion_kind":{"type":"string","maxLength":128,"minLength":1,"title":"Assertion Kind"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","key","assertion_kind"],"title":"SimulationCaseAssertionEval"},"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.\n\n``total`` counts every case that matches ``service_id``, ``tags`` and ``search``.","operationId":"list-simulation-cases","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"exclusiveMinimum":0,"default":50,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"title":"Continuation Token"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Sort axes as `+field` or `-field`, applied left to right. Newest created first when empty.","default":[],"title":"Sort By"},"description":"Sort axes as `+field` or `-field`, applied left to right. Newest created first when empty."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/SearchString"},{"type":"null"}],"description":"Case-insensitive substring match on the case description.","title":"Search"},"description":"Case-insensitive substring match on the case description."},{"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"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationCaseListResponse"}}}},"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://platform.api-us.concurrence.com","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"}},"additionalProperties":false,"type":"object","required":["cases"],"title":"CreateSimulationCasesRequest"},"CreateSimulationCaseItem":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"description":{"type":"string","maxLength":2000,"minLength":1,"title":"Description"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"scenario":{"$ref":"#/components/schemas/SimulationCaseScenario"},"grounding":{"$ref":"#/components/schemas/SimulationCaseGrounding"},"evals":{"items":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseMetricEval"},{"$ref":"#/components/schemas/SimulationCaseAssertionEval"}]},"type":"array","maxItems":100,"title":"Evals"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20,"title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"}},"additionalProperties":false,"type":"object","required":["description","scenario"],"title":"CreateSimulationCaseItem","description":"One durable simulation case to create."},"SimulationCaseScenario":{"properties":{"instructions":{"type":"string","maxLength":10000,"minLength":1,"title":"Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message","default":""},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"}},"type":"object","required":["instructions"],"title":"SimulationCaseScenario","description":"Runnable patient-side scenario content for a saved case."},"SimulationCaseGrounding":{"properties":{"patient_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Patient Entity Id"}},"type":"object","title":"SimulationCaseGrounding","description":"Optional bindings that start the sim from existing workspace data."},"SimulationCaseMetricEval":{"properties":{"type":{"type":"string","const":"metric","title":"Type"},"metric_key":{"type":"string","maxLength":128,"minLength":1,"title":"Metric Key"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","metric_key"],"title":"SimulationCaseMetricEval"},"SimulationCaseAssertionEval":{"properties":{"type":{"type":"string","const":"assertion","title":"Type"},"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"assertion_kind":{"type":"string","maxLength":128,"minLength":1,"title":"Assertion Kind"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","key","assertion_kind"],"title":"SimulationCaseAssertionEval"},"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"},"description":{"type":"string","maxLength":2000,"title":"Description"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"scenario":{"$ref":"#/components/schemas/SimulationCaseScenario"},"grounding":{"$ref":"#/components/schemas/SimulationCaseGrounding"},"evals":{"items":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseMetricEval"},{"$ref":"#/components/schemas/SimulationCaseAssertionEval"}]},"type":"array","title":"Evals"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"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"],"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"}}]}}}}
```

## List Simulation Suite Cases

> List the cases a suite selects, one page per call.\
> \
> A suite selects its explicit \`\`case\_ids\`\` plus every case that carries all of\
> its \`\`required\_tags\`\`, so explicit, tag-defined and hybrid suites all resolve\
> here. Without \`\`search\`\`, \`\`total\`\` equals the suite's \`\`case\_count\`\`.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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":{"SearchString":{"type":"string","maxLength":200,"minLength":1},"SimulationCaseListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SimulationCaseResponse"},"type":"array","title":"Items"},"total":{"type":"integer","minimum":0,"title":"Total","description":"Cases matching the filters and search, across every page."},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"title":"Continuation Token"}},"type":"object","required":["items","total","has_more"],"title":"SimulationCaseListResponse"},"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"},"description":{"type":"string","maxLength":2000,"title":"Description"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"scenario":{"$ref":"#/components/schemas/SimulationCaseScenario"},"grounding":{"$ref":"#/components/schemas/SimulationCaseGrounding"},"evals":{"items":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseMetricEval"},{"$ref":"#/components/schemas/SimulationCaseAssertionEval"}]},"type":"array","title":"Evals"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"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"],"title":"SimulationCaseResponse","description":"HTTP response shape for durable simulation cases."},"SimulationCaseScenario":{"properties":{"instructions":{"type":"string","maxLength":10000,"minLength":1,"title":"Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message","default":""},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"}},"type":"object","required":["instructions"],"title":"SimulationCaseScenario","description":"Runnable patient-side scenario content for a saved case."},"SimulationCaseGrounding":{"properties":{"patient_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Patient Entity Id"}},"type":"object","title":"SimulationCaseGrounding","description":"Optional bindings that start the sim from existing workspace data."},"SimulationCaseMetricEval":{"properties":{"type":{"type":"string","const":"metric","title":"Type"},"metric_key":{"type":"string","maxLength":128,"minLength":1,"title":"Metric Key"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","metric_key"],"title":"SimulationCaseMetricEval"},"SimulationCaseAssertionEval":{"properties":{"type":{"type":"string","const":"assertion","title":"Type"},"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"assertion_kind":{"type":"string","maxLength":128,"minLength":1,"title":"Assertion Kind"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","key","assertion_kind"],"title":"SimulationCaseAssertionEval"},"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/suites/{suite_id}/cases":{"get":{"tags":["Simulations"],"summary":"List Simulation Suite Cases","description":"List the cases a suite selects, one page per call.\n\nA suite selects its explicit ``case_ids`` plus every case that carries all of\nits ``required_tags``, so explicit, tag-defined and hybrid suites all resolve\nhere. Without ``search``, ``total`` equals the suite's ``case_count``.","operationId":"list-simulation-suite-cases","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"suite_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Suite Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"exclusiveMinimum":0,"default":50,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"title":"Continuation Token"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Sort axes as `+field` or `-field`, applied left to right. Newest created first when empty.","default":[],"title":"Sort By"},"description":"Sort axes as `+field` or `-field`, applied left to right. Newest created first when empty."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/SearchString"},{"type":"null"}],"description":"Case-insensitive substring match on the case description.","title":"Search"},"description":"Case-insensitive substring match on the case description."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationCaseListResponse"}}}},"404":{"description":"Simulation suite not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## 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://platform.api-us.concurrence.com","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"},"description":{"type":"string","maxLength":2000,"title":"Description"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"scenario":{"$ref":"#/components/schemas/SimulationCaseScenario"},"grounding":{"$ref":"#/components/schemas/SimulationCaseGrounding"},"evals":{"items":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseMetricEval"},{"$ref":"#/components/schemas/SimulationCaseAssertionEval"}]},"type":"array","title":"Evals"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"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"],"title":"SimulationCaseResponse","description":"HTTP response shape for durable simulation cases."},"SimulationCaseScenario":{"properties":{"instructions":{"type":"string","maxLength":10000,"minLength":1,"title":"Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message","default":""},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"}},"type":"object","required":["instructions"],"title":"SimulationCaseScenario","description":"Runnable patient-side scenario content for a saved case."},"SimulationCaseGrounding":{"properties":{"patient_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Patient Entity Id"}},"type":"object","title":"SimulationCaseGrounding","description":"Optional bindings that start the sim from existing workspace data."},"SimulationCaseMetricEval":{"properties":{"type":{"type":"string","const":"metric","title":"Type"},"metric_key":{"type":"string","maxLength":128,"minLength":1,"title":"Metric Key"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","metric_key"],"title":"SimulationCaseMetricEval"},"SimulationCaseAssertionEval":{"properties":{"type":{"type":"string","const":"assertion","title":"Type"},"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"assertion_kind":{"type":"string","maxLength":128,"minLength":1,"title":"Assertion Kind"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","key","assertion_kind"],"title":"SimulationCaseAssertionEval"},"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 and remove it from every suite that lists it.\
> \
> The case row and its id in the workspace's suites go in one transaction, so\
> no suite keeps an id that resolves to nothing. A suite listing the case\
> doesn't block the delete (no 409): a suite selects cases from the library,\
> and the audit event records which suites lost the case.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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 and remove it from every suite that lists it.\n\nThe case row and its id in the workspace's suites go in one transaction, so\nno suite keeps an id that resolves to nothing. A suite listing the case\ndoesn't block the delete (no 409): a suite selects cases from the library,\nand the audit event records which suites lost the 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://platform.api-us.concurrence.com","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":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseScenario"},{"type":"null"}]},"grounding":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseGrounding"},{"type":"null"}]},"evals":{"anyOf":[{"items":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseMetricEval"},{"$ref":"#/components/schemas/SimulationCaseAssertionEval"}]},"type":"array","maxItems":100},{"type":"null"}],"title":"Evals"},"tags":{"anyOf":[{"items":{"type":"string","maxLength":128},"type":"array","maxItems":20},{"type":"null"}],"title":"Tags"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"additionalProperties":false,"type":"object","title":"UpdateSimulationCaseRequest","description":"Partial update for one durable simulation case.\n\nMirrors the nested ``CreateSimulationCaseItem`` shape with every field\noptional so ``model_dump(exclude_unset=True)`` only emits the keys the\ncaller actually sent. Reuses the same nested submodels as create so the\ndurable fields (``scenario``, ``grounding``, ``evals``, ``metadata``) can\nbe PATCHed. ``extra=\"forbid\"`` rejects the retired pre-V192 flat fields\n(scenario_instructions, initial_message, temperament, fixtures,\nconstraints, target_spec, assertions, provenance) with 422 instead of\nsilently dropping them."},"SimulationCaseScenario":{"properties":{"instructions":{"type":"string","maxLength":10000,"minLength":1,"title":"Instructions"},"initial_message":{"type":"string","maxLength":2000,"title":"Initial Message","default":""},"temperament":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Temperament"}},"type":"object","required":["instructions"],"title":"SimulationCaseScenario","description":"Runnable patient-side scenario content for a saved case."},"SimulationCaseGrounding":{"properties":{"patient_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Patient Entity Id"}},"type":"object","title":"SimulationCaseGrounding","description":"Optional bindings that start the sim from existing workspace data."},"SimulationCaseMetricEval":{"properties":{"type":{"type":"string","const":"metric","title":"Type"},"metric_key":{"type":"string","maxLength":128,"minLength":1,"title":"Metric Key"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","metric_key"],"title":"SimulationCaseMetricEval"},"SimulationCaseAssertionEval":{"properties":{"type":{"type":"string","const":"assertion","title":"Type"},"key":{"type":"string","maxLength":128,"minLength":1,"title":"Key"},"assertion_kind":{"type":"string","maxLength":128,"minLength":1,"title":"Assertion Kind"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"params":{"additionalProperties":true,"type":"object","title":"Params"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Weight"}},"type":"object","required":["type","key","assertion_kind"],"title":"SimulationCaseAssertionEval"},"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"},"description":{"type":"string","maxLength":2000,"title":"Description"},"persona":{"additionalProperties":true,"type":"object","title":"Persona"},"scenario":{"$ref":"#/components/schemas/SimulationCaseScenario"},"grounding":{"$ref":"#/components/schemas/SimulationCaseGrounding"},"evals":{"items":{"anyOf":[{"$ref":"#/components/schemas/SimulationCaseMetricEval"},{"$ref":"#/components/schemas/SimulationCaseAssertionEval"}]},"type":"array","title":"Evals"},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"Tags"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"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"],"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://platform.api-us.concurrence.com","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"},"error":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Error"},"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"},"eval_results":{"items":{"$ref":"#/components/schemas/SimulationEvalResultResponse"},"type":"array","title":"Eval Results"},"eval_result_count":{"type":"integer","title":"Eval Result Count","default":0},"eval_pass_count":{"type":"integer","title":"Eval Pass Count","default":0},"eval_fail_count":{"type":"integer","title":"Eval Fail Count","default":0},"eval_error_count":{"type":"integer","title":"Eval Error Count","default":0},"checks":{"items":{"$ref":"#/components/schemas/EvaluationResultView"},"type":"array","title":"Checks","description":"Normalized per-check view of ``eval_results``. Raw ``eval_results``\nstay intact; this rides alongside so the console renders checks without\nreverse-engineering actual.latest vs actual.judge vs score.","readOnly":true}},"type":"object","required":["id","service_id","status","checks"],"title":"SimulationRunResponse","description":"Full run payload — used by GET /runs/{run_id} for replay flows."},"SimulationEvalResultResponse":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"assertion_kind":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Assertion Kind"},"metric_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Metric Key"},"status":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Status"},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"rationale":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Rationale"},"justification":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Justification"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"details":{"additionalProperties":true,"type":"object","title":"Details"},"definition":{"additionalProperties":true,"type":"object","title":"Definition"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["eval_key","eval_type","status"],"title":"SimulationEvalResultResponse"},"EvaluationResultView":{"properties":{"source_type":{"type":"string","enum":["metric","assertion"],"title":"Source Type"},"key":{"type":"string","maxLength":128,"title":"Key"},"label":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Label"},"value_type":{"anyOf":[{"type":"string","enum":["numeric","boolean","categorical","text","structured"]},{"type":"null"}],"title":"Value Type"},"evaluation_method":{"anyOf":[{"type":"string","enum":["threshold","equals","contains","regex","tool_called","llm_judge","custom"]},{"type":"null"}],"title":"Evaluation Method"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"expected_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Expected Display"},"actual_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Actual Display"},"verdict":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Verdict"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"rationale":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Rationale"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"run_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"trace_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Trace Id"}},"type":"object","required":["source_type","key","verdict"],"title":"EvaluationResultView","description":"One check as the console renders it, derived from a single eval result.\n\nBoth metric and assertion verdicts normalize to this shape so the frontend\nrenders a check without knowing where the value was stored."},"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"}}}}}}}}}
```

## Get Simulation Performance

> Aggregate recent graded (case/suite) runs into the Simulations overview:\
> overall pass rate, per-metric trend series, and per-case / per-suite rollups\
> (each with its per-conversation verdicts).\
> \
> \`\`limit\`\` (1 to 50) bounds how many recent runs are read. One request\
> replaces the console's former one-fetch-per-run fan-out.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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":{"SimulationPerformanceResponse":{"properties":{"overview":{"$ref":"#/components/schemas/SimPerformanceOverviewResponse"},"metrics":{"items":{"$ref":"#/components/schemas/SimMetricPerfResponse"},"type":"array","title":"Metrics"},"by_case":{"items":{"$ref":"#/components/schemas/SimCasePerfResponse"},"type":"array","title":"By Case"},"by_suite":{"items":{"$ref":"#/components/schemas/SimSuitePerfResponse"},"type":"array","title":"By Suite"}},"type":"object","required":["overview"],"title":"SimulationPerformanceResponse","description":"Aggregated Simulations overview: one request in place of the console's\nformer one-detail-fetch-per-run fan-out."},"SimPerformanceOverviewResponse":{"properties":{"overall_pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Overall Pass Rate","description":"passed / (passed + failed); null when there is no passed or failed verdict"},"evals_run":{"type":"integer","title":"Evals Run","description":"Passed + failed verdicts: the overall_pass_rate denominator","default":0},"error_count":{"type":"integer","title":"Error Count","description":"Verdicts where grading broke; not in overall_pass_rate","default":0},"pending_count":{"type":"integer","title":"Pending Count","description":"Verdicts not graded yet; not in overall_pass_rate","default":0},"skipped_count":{"type":"integer","title":"Skipped Count","description":"Verdicts that did not apply; not in overall_pass_rate","default":0},"needs_attention_count":{"type":"integer","title":"Needs Attention Count","default":0},"runs_analyzed":{"type":"integer","title":"Runs Analyzed","default":0}},"type":"object","title":"SimPerformanceOverviewResponse"},"SimMetricPerfResponse":{"properties":{"metric_key":{"type":"string","maxLength":128,"title":"Metric Key"},"label":{"type":"string","maxLength":128,"title":"Label"},"per_run":{"items":{"$ref":"#/components/schemas/SimMetricRunPointResponse"},"type":"array","title":"Per Run"},"results":{"items":{"$ref":"#/components/schemas/SimulationEvalResultResponse"},"type":"array","title":"Results"},"checks":{"items":{"$ref":"#/components/schemas/EvaluationResultView"},"type":"array","title":"Checks","description":"Normalized per-check view of ``results`` (mirrors SimCaseAssertionResponse)\nso the console renders each metric drill-down verdict without parsing raw shapes.","readOnly":true}},"type":"object","required":["metric_key","label","checks"],"title":"SimMetricPerfResponse"},"SimMetricRunPointResponse":{"properties":{"at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"At"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"passed":{"type":"integer","title":"Passed","default":0},"measured":{"type":"integer","title":"Measured","description":"Passed + failed verdicts; error, pending and skipped are excluded","default":0}},"type":"object","title":"SimMetricRunPointResponse","description":"One run's contribution to a metric: the mean value that run (null for\nnon-numeric metrics) plus how many conversations passed / were measured."},"SimulationEvalResultResponse":{"properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Id"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"assertion_kind":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Assertion Kind"},"metric_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Metric Key"},"status":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Status"},"passed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Passed"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"rationale":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Rationale"},"justification":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Justification"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"details":{"additionalProperties":true,"type":"object","title":"Details"},"definition":{"additionalProperties":true,"type":"object","title":"Definition"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["eval_key","eval_type","status"],"title":"SimulationEvalResultResponse"},"EvaluationResultView":{"properties":{"source_type":{"type":"string","enum":["metric","assertion"],"title":"Source Type"},"key":{"type":"string","maxLength":128,"title":"Key"},"label":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Label"},"value_type":{"anyOf":[{"type":"string","enum":["numeric","boolean","categorical","text","structured"]},{"type":"null"}],"title":"Value Type"},"evaluation_method":{"anyOf":[{"type":"string","enum":["threshold","equals","contains","regex","tool_called","llm_judge","custom"]},{"type":"null"}],"title":"Evaluation Method"},"expected":{"anyOf":[{},{"type":"null"}],"title":"Expected"},"actual":{"anyOf":[{},{"type":"null"}],"title":"Actual"},"expected_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Expected Display"},"actual_display":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Actual Display"},"verdict":{"type":"string","enum":["passed","failed","pending","skipped","error"],"title":"Verdict"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"rationale":{"anyOf":[{"type":"string","maxLength":8000},{"type":"null"}],"title":"Rationale"},"references":{"items":{"type":"integer"},"type":"array","maxItems":100,"title":"References"},"run_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Run Id"},"case_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Case Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"trace_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Trace Id"}},"type":"object","required":["source_type","key","verdict"],"title":"EvaluationResultView","description":"One check as the console renders it, derived from a single eval result.\n\nBoth metric and assertion verdicts normalize to this shape so the frontend\nrenders a check without knowing where the value was stored."},"SimCasePerfResponse":{"properties":{"case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Case Id"},"case_name":{"type":"string","maxLength":512,"title":"Case Name"},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate","description":"passed / (passed + failed); null when there is no passed or failed verdict"},"passed":{"type":"integer","title":"Passed","default":0},"failed":{"type":"integer","title":"Failed","default":0},"error":{"type":"integer","title":"Error","description":"Verdicts where grading broke; not in the pass_rate denominator","default":0},"pending":{"type":"integer","title":"Pending","description":"Verdicts not graded yet; not in the pass_rate denominator","default":0},"skipped":{"type":"integer","title":"Skipped","description":"Verdicts that did not apply; not in the pass_rate denominator","default":0},"measured":{"type":"integer","title":"Measured","description":"passed + failed","default":0},"latest_run_id":{"type":"string","format":"uuid","title":"Latest Run Id"},"latest_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Run At"},"assertions":{"items":{"$ref":"#/components/schemas/SimCaseAssertionResponse"},"type":"array","title":"Assertions"}},"type":"object","required":["case_name","latest_run_id"],"title":"SimCasePerfResponse"},"SimCaseAssertionResponse":{"properties":{"eval_key":{"type":"string","maxLength":128,"title":"Eval Key"},"eval_type":{"type":"string","enum":["assertion","metric"],"title":"Eval Type"},"passed":{"type":"integer","title":"Passed","default":0},"failed":{"type":"integer","title":"Failed","default":0},"error":{"type":"integer","title":"Error","description":"Verdicts where grading broke; not in the pass_rate denominator","default":0},"pending":{"type":"integer","title":"Pending","description":"Verdicts not graded yet; not in the pass_rate denominator","default":0},"skipped":{"type":"integer","title":"Skipped","description":"Verdicts that did not apply; not in the pass_rate denominator","default":0},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate","description":"passed / (passed + failed); null when there is no passed or failed verdict"},"results":{"items":{"$ref":"#/components/schemas/SimulationEvalResultResponse"},"type":"array","title":"Results"},"checks":{"items":{"$ref":"#/components/schemas/EvaluationResultView"},"type":"array","title":"Checks","description":"Normalized per-check view of ``results`` (metric + assertion verdicts),\nso the console renders each drill-down verdict without parsing raw shapes.","readOnly":true}},"type":"object","required":["eval_key","eval_type","checks"],"title":"SimCaseAssertionResponse"},"SimSuitePerfResponse":{"properties":{"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite Id"},"suite_name":{"type":"string","maxLength":512,"title":"Suite Name"},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate","description":"passed / (passed + failed); null when there is no passed or failed verdict"},"passed":{"type":"integer","title":"Passed","default":0},"failed":{"type":"integer","title":"Failed","default":0},"error":{"type":"integer","title":"Error","description":"Verdicts where grading broke; not in the pass_rate denominator","default":0},"pending":{"type":"integer","title":"Pending","description":"Verdicts not graded yet; not in the pass_rate denominator","default":0},"skipped":{"type":"integer","title":"Skipped","description":"Verdicts that did not apply; not in the pass_rate denominator","default":0},"measured":{"type":"integer","title":"Measured","description":"passed + failed","default":0},"latest_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Run At"},"cases":{"items":{"$ref":"#/components/schemas/SimCasePerfResponse"},"type":"array","title":"Cases"}},"type":"object","required":["suite_name"],"title":"SimSuitePerfResponse"},"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/performance":{"get":{"tags":["Simulations"],"summary":"Get Simulation Performance","description":"Aggregate recent graded (case/suite) runs into the Simulations overview:\noverall pass rate, per-metric trend series, and per-case / per-suite rollups\n(each with its per-conversation verdicts).\n\n``limit`` (1 to 50) bounds how many recent runs are read. One request\nreplaces the console's former one-fetch-per-run fan-out.","operationId":"get-simulation-performance","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","maximum":50,"minimum":1,"default":15,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationPerformanceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Complete Simulation Run

> Finish a running run: failed when \`\`error\`\` is set, otherwise completed.\
> \
> A run finishes once. Completing a finished run returns 409 and leaves it as it was.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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":{"CompleteSimulationRunResponse":{"properties":{"status":{"type":"string","enum":["completed","failed"],"title":"Status"}},"type":"object","required":["status"],"title":"CompleteSimulationRunResponse"},"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","description":"Finish a running run: failed when ``error`` is set, otherwise completed.\n\nA run finishes once. Completing a finished run returns 409 and leaves it as it was.","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","maxLength":500},{"type":"null"}],"description":"Failure reason. Set it to finish the run as failed.","title":"Error"},"description":"Failure reason. Set it to finish the run as failed."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteSimulationRunResponse"}}}},"404":{"description":"Run not found"},"409":{"description":"Run has already finished"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Promote Simulation Session

> Promote a run-less (interactive playground) session into a coverage run.\
> \
> Interactive text sessions are created run-less, so \`\`fork\`\` — which requires\
> a \`\`run\_id\`\` — 404s on them. This creates a coverage run, binds the existing\
> agent-engine session to it (\`\`adopt-run\`\`, a Valkey meta update — the session\
> itself is not recreated), and writes the platform-api \`\`SimulationCoverageSession\`\`\
> record that \`\`get\_session\_metadata\`\` returns, unblocking fork/score.\
> \
> Idempotent: a session that already has a coverage record returns its existing\
> run with \`\`already\_bound=True\`\`.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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":{"PromoteSessionResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id","description":"The coverage run the session is now bound to"},"session_id":{"type":"string","title":"Session Id","description":"The promoted session id (unchanged)"},"already_bound":{"type":"boolean","title":"Already Bound","description":"True when the session was already run-scoped; the existing run is returned unchanged"}},"type":"object","required":["run_id","session_id","already_bound"],"title":"PromoteSessionResponse","description":"Result of binding a run-less session to a (newly created) coverage run."},"SimulationProxyErrorResponse":{"properties":{"detail":{"anyOf":[{"type":"string"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Detail"}},"type":"object","required":["detail"],"title":"SimulationProxyErrorResponse","description":"Error envelope for simulation routes that proxy agent-engine.\n\n``detail`` is a string for forwarded runtime/configuration errors and a\nstructured list for FastAPI request validation failures. Both share HTTP\n422, so the published contract must admit both shapes."}}},"paths":{"/v1/{workspace_id}/simulations/sessions/{session_id}/promote":{"post":{"tags":["Simulations"],"summary":"Promote Simulation Session","description":"Promote a run-less (interactive playground) session into a coverage run.\n\nInteractive text sessions are created run-less, so ``fork`` — which requires\na ``run_id`` — 404s on them. This creates a coverage run, binds the existing\nagent-engine session to it (``adopt-run``, a Valkey meta update — the session\nitself is not recreated), and writes the platform-api ``SimulationCoverageSession``\nrecord that ``get_session_metadata`` returns, unblocking fork/score.\n\nIdempotent: a session that already has a coverage record returns its existing\nrun with ``already_bound=True``.","operationId":"promote-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"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromoteSessionResponse"}}}},"404":{"description":"Simulation session or configuration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"422":{"description":"Request validation or simulation configuration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"502":{"description":"Simulation runtime error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"503":{"description":"Voice agent not reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}}}}}}}
```

## Create Simulation Session

> Create a simulation session within a run. Proxies to agent-engine.\
> \
> The run must be in the workspace (404 otherwise) and \`\`service\_id\`\` must be\
> the run's service (422 otherwise), both checked before agent-engine is called.\
> \
> 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://platform.api-us.concurrence.com","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":{"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","maxLength":128},"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"},"SimulationProxyErrorResponse":{"properties":{"detail":{"anyOf":[{"type":"string"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Detail"}},"type":"object","required":["detail"],"title":"SimulationProxyErrorResponse","description":"Error envelope for simulation routes that proxy agent-engine.\n\n``detail`` is a string for forwarded runtime/configuration errors and a\nstructured list for FastAPI request validation failures. Both share HTTP\n422, so the published contract must admit both shapes."}}},"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\nThe run must be in the workspace (404 otherwise) and ``service_id`` must be\nthe run's service (422 otherwise), both checked before agent-engine is called.\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/CreateSessionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationSessionResponse"}}}},"404":{"description":"Run or simulation configuration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"422":{"description":"Request validation or simulation configuration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"502":{"description":"Simulation runtime error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"503":{"description":"Voice agent not reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}}}}}}}
```

## Simulation Step

> Step the session in the path and auto-store the turn observation.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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":{"StepSessionRequest":{"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"},"session_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Session Id","description":"Leave unset: the path names the session. A value that differs from the path returns 422."}},"type":"object","required":["caller_text"],"title":"StepSessionRequest","description":"One caller turn for the session named in the path."},"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"},"SimulationProxyErrorResponse":{"properties":{"detail":{"anyOf":[{"type":"string"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Detail"}},"type":"object","required":["detail"],"title":"SimulationProxyErrorResponse","description":"Error envelope for simulation routes that proxy agent-engine.\n\n``detail`` is a string for forwarded runtime/configuration errors and a\nstructured list for FastAPI request validation failures. Both share HTTP\n422, so the published contract must admit both shapes."}}},"paths":{"/v1/{workspace_id}/simulations/sessions/{session_id}/step":{"post":{"tags":["Simulations"],"summary":"Simulation Step","description":"Step the session in the path 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","maxLength":64,"title":"Session Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StepSessionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationStepResponse"}}}},"404":{"description":"Simulation session or configuration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"422":{"description":"Request validation or simulation configuration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"502":{"description":"Simulation runtime error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"503":{"description":"Voice agent not reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}}}}}}}
```

## 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://platform.api-us.concurrence.com","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"},"SimulationForkResponse":{"properties":{"parent_session_id":{"type":"string","title":"Parent Session Id"},"fork_turn_index":{"type":"integer","title":"Fork Turn Index","description":"The parent's turn count when it forked. Each branch's first turn is stored at the next index."},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"branches":{"items":{"$ref":"#/components/schemas/ForkBranch"},"type":"array","title":"Branches"}},"type":"object","required":["parent_session_id","fork_turn_index","service_id","branches"],"title":"SimulationForkResponse","description":"One branch per alternative, in request order."},"ForkBranch":{"properties":{"session_id":{"type":"string","title":"Session Id"},"observation":{"anyOf":[{"$ref":"#/components/schemas/ForkObservation"},{"type":"null"}],"description":"The branch's first turn. Null when the branch failed."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Why the branch failed. Null when it stepped."}},"type":"object","required":["session_id"],"title":"ForkBranch"},"ForkObservation":{"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"},"caller_text":{"type":"string","title":"Caller Text"}},"type":"object","required":["state_before","state_after","state_changed","agent_text","is_terminal","caller_text"],"title":"ForkObservation"},"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."},"SimulationProxyErrorResponse":{"properties":{"detail":{"anyOf":[{"type":"string"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Detail"}},"type":"object","required":["detail"],"title":"SimulationProxyErrorResponse","description":"Error envelope for simulation routes that proxy agent-engine.\n\n``detail`` is a string for forwarded runtime/configuration errors and a\nstructured list for FastAPI request validation failures. Both share HTTP\n422, so the published contract must admit both shapes."}}},"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":{"$ref":"#/components/schemas/SimulationForkResponse"}}}},"404":{"description":"Simulation session or configuration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"422":{"description":"Request validation or simulation configuration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"502":{"description":"Simulation runtime error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"503":{"description":"Voice agent not reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}}}}}}}
```

## Score Simulation Session

> ASI assigns a score to a completed simulation session.\
> \
> 404 when the workspace has no coverage session with this id, such as a\
> run-less playground session that was never promoted.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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.\n\n404 when the workspace has no coverage session with this id, such as a\nrun-less playground session that was never promoted.","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"}}}},"404":{"description":"Simulation session not found"},"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://platform.api-us.concurrence.com","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":{"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","maxLength":128},"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"},"SimulationProxyErrorResponse":{"properties":{"detail":{"anyOf":[{"type":"string"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Detail"}},"type":"object","required":["detail"],"title":"SimulationProxyErrorResponse","description":"Error envelope for simulation routes that proxy agent-engine.\n\n``detail`` is a string for forwarded runtime/configuration errors and a\nstructured list for FastAPI request validation failures. Both share HTTP\n422, so the published contract must admit both shapes."}}},"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/CreateSessionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationSessionResponse"}}}},"404":{"description":"Simulation session or configuration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"422":{"description":"Request validation or simulation configuration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"502":{"description":"Simulation runtime error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"503":{"description":"Voice agent not reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}}},"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://platform.api-us.concurrence.com","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"},"SimulationProxyErrorResponse":{"properties":{"detail":{"anyOf":[{"type":"string"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Detail"}},"type":"object","required":["detail"],"title":"SimulationProxyErrorResponse","description":"Error envelope for simulation routes that proxy agent-engine.\n\n``detail`` is a string for forwarded runtime/configuration errors and a\nstructured list for FastAPI request validation failures. Both share HTTP\n422, so the published contract must admit both shapes."}}},"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"}}}},"404":{"description":"Simulation session or configuration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"422":{"description":"Request validation or simulation configuration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"502":{"description":"Simulation runtime error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"503":{"description":"Voice agent not reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}}},"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://platform.api-us.concurrence.com","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"},"SimulationProxyErrorResponse":{"properties":{"detail":{"anyOf":[{"type":"string"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Detail"}},"type":"object","required":["detail"],"title":"SimulationProxyErrorResponse","description":"Error envelope for simulation routes that proxy agent-engine.\n\n``detail`` is a string for forwarded runtime/configuration errors and a\nstructured list for FastAPI request validation failures. Both share HTTP\n422, so the published contract must admit both shapes."}}},"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"}}}},"404":{"description":"Simulation session or configuration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"422":{"description":"Request validation or simulation configuration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"502":{"description":"Simulation runtime error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"503":{"description":"Voice agent not reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}}},"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://platform.api-us.concurrence.com","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"},"SimulationProxyErrorResponse":{"properties":{"detail":{"anyOf":[{"type":"string"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Detail"}},"type":"object","required":["detail"],"title":"SimulationProxyErrorResponse","description":"Error envelope for simulation routes that proxy agent-engine.\n\n``detail`` is a string for forwarded runtime/configuration errors and a\nstructured list for FastAPI request validation failures. Both share HTTP\n422, so the published contract must admit both shapes."}}},"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"}}}},"404":{"description":"Simulation session or configuration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"422":{"description":"Request validation or simulation configuration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"502":{"description":"Simulation runtime error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"503":{"description":"Voice agent not reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}}}}}}}
```

## 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://platform.api-us.concurrence.com","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"},"SimulationProxyErrorResponse":{"properties":{"detail":{"anyOf":[{"type":"string"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Detail"}},"type":"object","required":["detail"],"title":"SimulationProxyErrorResponse","description":"Error envelope for simulation routes that proxy agent-engine.\n\n``detail`` is a string for forwarded runtime/configuration errors and a\nstructured list for FastAPI request validation failures. Both share HTTP\n422, so the published contract must admit both shapes."}}},"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"}}}},"404":{"description":"Simulation session or configuration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"422":{"description":"Request validation or simulation configuration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"502":{"description":"Simulation runtime error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"503":{"description":"Voice agent not reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}}}}}}}
```

## 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://platform.api-us.concurrence.com","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"},"SimulationProxyErrorResponse":{"properties":{"detail":{"anyOf":[{"type":"string"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Detail"}},"type":"object","required":["detail"],"title":"SimulationProxyErrorResponse","description":"Error envelope for simulation routes that proxy agent-engine.\n\n``detail`` is a string for forwarded runtime/configuration errors and a\nstructured list for FastAPI request validation failures. Both share HTTP\n422, so the published contract must admit both shapes."}}},"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"}}}},"404":{"description":"Simulation session or configuration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"422":{"description":"Request validation or simulation configuration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"502":{"description":"Simulation runtime error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}},"503":{"description":"Voice agent not reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationProxyErrorResponse"}}}}}}}}}
```

## 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://platform.api-us.concurrence.com","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":{"SimulationCoverageGraphResponse":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"total_sessions":{"type":"integer","title":"Total Sessions"},"total_turns":{"type":"integer","title":"Total Turns"},"total_forks":{"type":"integer","title":"Total Forks"},"coverage_percentage":{"type":"number","title":"Coverage Percentage"},"state_nodes":{"items":{"$ref":"#/components/schemas/CoverageStateNode"},"type":"array","title":"State Nodes"},"edges":{"items":{"$ref":"#/components/schemas/CoverageEdge"},"type":"array","title":"Edges"},"tree":{"$ref":"#/components/schemas/CoverageTree"},"sessions":{"items":{"$ref":"#/components/schemas/CoverageSession"},"type":"array","title":"Sessions"},"turns":{"anyOf":[{"items":{"$ref":"#/components/schemas/CoverageTurn"},"type":"array"},{"type":"null"}],"title":"Turns","description":"Every stored turn in order. Set only with include_turns=true."},"metric_status":{"anyOf":[{"type":"string","enum":["pending","available","unavailable"]},{"type":"null"}],"title":"Metric Status","description":"Delayed-metric availability for the run. Set only when the request names a run_id."},"metric_result_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Metric Result Count"},"metrics_last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Metrics Last Checked At"}},"type":"object","required":["service_id","run_id","total_sessions","total_turns","total_forks","coverage_percentage","state_nodes","edges","tree","sessions"],"title":"SimulationCoverageGraphResponse","description":"The service's context graph states and transitions, overlaid with the stored turns."},"CoverageStateNode":{"properties":{"id":{"type":"string","title":"Id","description":"The state name."},"type":{"type":"string","title":"Type","description":"The state type in the context graph, or `unknown` for a state seen only in turns."},"theoretical":{"type":"boolean","title":"Theoretical","description":"The state is in the service's context graph."},"observed":{"type":"boolean","title":"Observed","description":"At least one stored turn started in this state."},"turn_count":{"type":"integer","title":"Turn Count"},"session_count":{"type":"integer","title":"Session Count"},"self_loop_count":{"type":"integer","title":"Self Loop Count"},"transition_out_count":{"type":"integer","title":"Transition Out Count"},"pass_count":{"type":"integer","title":"Pass Count"},"fail_count":{"type":"integer","title":"Fail Count"},"unknown_count":{"type":"integer","title":"Unknown Count"},"is_terminal":{"type":"boolean","title":"Is Terminal"},"first_seen_turn":{"type":"integer","title":"First Seen Turn","description":"Index of the first turn that started in this state, or -1."},"tools_used":{"items":{"type":"string"},"type":"array","title":"Tools Used"},"average_empathy_tier":{"type":"number","title":"Average Empathy Tier"},"average_engine_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Engine Ms"},"average_nav_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Nav Ms"}},"type":"object","required":["id","type","theoretical","observed","turn_count","session_count","self_loop_count","transition_out_count","pass_count","fail_count","unknown_count","is_terminal","first_seen_turn","tools_used","average_empathy_tier","average_engine_ms","average_nav_ms"],"title":"CoverageStateNode"},"CoverageEdge":{"properties":{"source":{"type":"string","title":"Source"},"target":{"type":"string","title":"Target"},"type":{"type":"string","enum":["transition","self_loop"],"title":"Type"},"theoretical":{"type":"boolean","title":"Theoretical","description":"The transition is an exit condition in the service's context graph."},"observed":{"type":"boolean","title":"Observed"},"frequency":{"type":"integer","title":"Frequency"},"first_seen_turn":{"type":"integer","title":"First Seen Turn","description":"Index of the first turn that took this edge, or -1."}},"type":"object","required":["source","target","type","theoretical","observed","frequency","first_seen_turn"],"title":"CoverageEdge"},"CoverageTree":{"properties":{"root_sessions":{"items":{"type":"string"},"type":"array","title":"Root Sessions"},"forks":{"items":{"$ref":"#/components/schemas/CoverageFork"},"type":"array","title":"Forks"}},"type":"object","required":["root_sessions","forks"],"title":"CoverageTree"},"CoverageFork":{"properties":{"parent_session_id":{"type":"string","title":"Parent Session Id"},"fork_turn_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fork Turn Index"},"children":{"items":{"type":"string"},"type":"array","title":"Children"}},"type":"object","required":["parent_session_id","fork_turn_index","children"],"title":"CoverageFork"},"CoverageSession":{"properties":{"metric_status":{"anyOf":[{"type":"string","enum":["pending","available","unavailable"]},{"type":"null"}],"title":"Metric Status"},"metric_result_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Metric Result Count"},"metrics_last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Metrics Last Checked At"},"immediate_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Immediate Score","description":"The session's score, the same value as score."},"immediate_score_rationale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Immediate Score Rationale"},"session_id":{"type":"string","title":"Session Id"},"parent_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Session Id"},"fork_turn_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fork Turn Index"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"total_turns":{"type":"integer","title":"Total Turns"},"terminal_reached":{"type":"boolean","title":"Terminal Reached"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["session_id","parent_session_id","fork_turn_index","tags","total_turns","terminal_reached","score","created_at"],"title":"CoverageSession"},"CoverageTurn":{"properties":{"session_id":{"type":"string","title":"Session Id"},"turn_index":{"type":"integer","title":"Turn Index"},"state_before":{"type":"string","title":"State Before"},"state_after":{"type":"string","title":"State After"},"state_changed":{"type":"boolean","title":"State Changed"},"caller_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Text"},"agent_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Text"},"tools_called":{"items":{"type":"string"},"type":"array","title":"Tools Called"},"tool_call_details":{"items":{"$ref":"#/components/schemas/ToolCallDetail"},"type":"array","title":"Tool Call Details"},"empathy_tier":{"type":"integer","title":"Empathy Tier"},"is_terminal":{"type":"boolean","title":"Is Terminal"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"global_index":{"type":"integer","title":"Global Index"}},"type":"object","required":["session_id","turn_index","state_before","state_after","state_changed","caller_text","agent_text","tools_called","tool_call_details","empathy_tier","is_terminal","created_at","global_index"],"title":"CoverageTurn"},"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."},"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","format":"uuid"},{"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":{"$ref":"#/components/schemas/SimulationCoverageGraphResponse"}}}},"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://platform.api-us.concurrence.com","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":{"DeleteSimulationCoverageGraphResponse":{"properties":{"deleted_runs":{"type":"integer","title":"Deleted Runs"},"deleted_sessions":{"type":"integer","title":"Deleted Sessions"},"deleted_turns":{"type":"integer","title":"Deleted Turns"}},"type":"object","required":["deleted_runs","deleted_sessions","deleted_turns"],"title":"DeleteSimulationCoverageGraphResponse"},"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":{"$ref":"#/components/schemas/DeleteSimulationCoverageGraphResponse"}}}},"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://platform.api-us.concurrence.com","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":{"SimulationCoveragePathsResponse":{"properties":{"paths":{"items":{"$ref":"#/components/schemas/CoveragePath"},"type":"array","title":"Paths","description":"Most sessions first."}},"type":"object","required":["paths"],"title":"SimulationCoveragePathsResponse"},"CoveragePath":{"properties":{"trajectory":{"items":{"type":"string"},"type":"array","title":"Trajectory","description":"The states the sessions moved through, in order."},"session_count":{"type":"integer","title":"Session Count"},"session_ids":{"items":{"type":"string"},"type":"array","title":"Session Ids"},"average_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Score"},"average_turns":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Turns"},"is_complete":{"type":"boolean","title":"Is Complete","description":"At least one session on the path reached a terminal state."}},"type":"object","required":["trajectory","session_count","session_ids","average_score","average_turns","is_complete"],"title":"CoveragePath"},"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","format":"uuid"},{"type":"null"}],"title":"Run Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationCoveragePathsResponse"}}}},"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://platform.api-us.concurrence.com","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":{"SimulationSessionListResponse":{"properties":{"sessions":{"items":{"$ref":"#/components/schemas/src__routes__simulations__SimulationSessionListResponse__Item"},"type":"array","title":"Sessions","description":"Newest first."}},"type":"object","required":["sessions"],"title":"SimulationSessionListResponse"},"src__routes__simulations__SimulationSessionListResponse__Item":{"properties":{"metric_status":{"anyOf":[{"type":"string","enum":["pending","available","unavailable"]},{"type":"null"}],"title":"Metric Status"},"metric_result_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Metric Result Count"},"metrics_last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Metrics Last Checked At"},"immediate_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Immediate Score","description":"The session's score, the same value as score."},"immediate_score_rationale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Immediate Score Rationale"},"session_id":{"type":"string","title":"Session Id"},"run_id":{"type":"string","format":"uuid","title":"Run Id"},"parent_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Session Id"},"fork_turn_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fork Turn Index"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Bridge-written tags, such as `scenario_index:<n>`, `temperament:<x>` and `forked`."},"total_turns":{"type":"integer","title":"Total Turns"},"terminal_reached":{"type":"boolean","title":"Terminal Reached"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"score_rationale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Score Rationale"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["session_id","run_id","parent_session_id","fork_turn_index","tags","total_turns","terminal_reached","score","score_rationale","created_at"],"title":"Item"},"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","format":"uuid"},{"type":"null"}],"title":"Run Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationSessionListResponse"}}}},"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://platform.api-us.concurrence.com","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":{"SimulationSessionTurnsResponse":{"properties":{"session_id":{"type":"string","title":"Session Id"},"turns":{"items":{"$ref":"#/components/schemas/SimulationTurnResponse"},"type":"array","title":"Turns","description":"In turn order, at most 200."}},"type":"object","required":["session_id","turns"],"title":"SimulationSessionTurnsResponse"},"SimulationTurnResponse":{"properties":{"session_id":{"type":"string","title":"Session Id"},"turn_index":{"type":"integer","title":"Turn Index"},"state_before":{"type":"string","title":"State Before"},"state_after":{"type":"string","title":"State After"},"state_changed":{"type":"boolean","title":"State Changed"},"caller_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Text"},"agent_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Text"},"tools_called":{"items":{"type":"string"},"type":"array","title":"Tools Called"},"tool_call_details":{"items":{"$ref":"#/components/schemas/ToolCallDetail"},"type":"array","title":"Tool Call Details"},"empathy_tier":{"type":"integer","title":"Empathy Tier"},"is_terminal":{"type":"boolean","title":"Is Terminal"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"tools_available":{"items":{"type":"string"},"type":"array","title":"Tools Available"}},"type":"object","required":["session_id","turn_index","state_before","state_after","state_changed","caller_text","agent_text","tools_called","tool_call_details","empathy_tier","is_terminal","created_at","tools_available"],"title":"SimulationTurnResponse","description":"One stored turn of a simulation session."},"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."},"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":{"$ref":"#/components/schemas/SimulationSessionTurnsResponse"}}}},"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://platform.api-us.concurrence.com","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":{"SimulationTurnQueryResponse":{"properties":{"turns":{"items":{"$ref":"#/components/schemas/SimulationTurnResponse"},"type":"array","title":"Turns","description":"Newest first."}},"type":"object","required":["turns"],"title":"SimulationTurnQueryResponse"},"SimulationTurnResponse":{"properties":{"session_id":{"type":"string","title":"Session Id"},"turn_index":{"type":"integer","title":"Turn Index"},"state_before":{"type":"string","title":"State Before"},"state_after":{"type":"string","title":"State After"},"state_changed":{"type":"boolean","title":"State Changed"},"caller_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Text"},"agent_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Text"},"tools_called":{"items":{"type":"string"},"type":"array","title":"Tools Called"},"tool_call_details":{"items":{"$ref":"#/components/schemas/ToolCallDetail"},"type":"array","title":"Tool Call Details"},"empathy_tier":{"type":"integer","title":"Empathy Tier"},"is_terminal":{"type":"boolean","title":"Is Terminal"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"tools_available":{"items":{"type":"string"},"type":"array","title":"Tools Available"}},"type":"object","required":["session_id","turn_index","state_before","state_after","state_changed","caller_text","agent_text","tools_called","tool_call_details","empathy_tier","is_terminal","created_at","tools_available"],"title":"SimulationTurnResponse","description":"One stored turn of a simulation session."},"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."},"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","maximum":500,"minimum":1,"default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationTurnQueryResponse"}}}},"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://platform.api-us.concurrence.com","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"},"ConfigToPolicyResponse":{"properties":{"turn_policy":{"$ref":"#/components/schemas/TurnPolicyOverrides","description":"Only the fields the config sets. A field left out keeps its turn-policy default."}},"type":"object","required":["turn_policy"],"title":"ConfigToPolicyResponse"},"TurnPolicyOverrides":{"properties":{"greeting_shield_s":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Greeting Shield S"},"barge_in_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Barge In Enabled"},"block_forward_call":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Block Forward Call"},"safety_response":{"anyOf":[{"type":"string","enum":["stay_empathize","alert"]},{"type":"null"}],"title":"Safety Response"},"context_strategy":{"anyOf":[{"type":"string","const":"compact"},{"type":"null"}],"title":"Context Strategy"},"degradation_threshold":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Degradation Threshold"},"block_forward_call_after_turns":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Block Forward Call After Turns"}},"type":"object","title":"TurnPolicyOverrides"},"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":{"$ref":"#/components/schemas/ConfigToPolicyResponse"}}}},"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://platform.api-us.concurrence.com","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 suite or 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://platform.api-us.concurrence.com","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":{"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite Id"},"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"},"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite 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 suite or 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"}}]}}}}
```

## Run Simulation Suite

> Run a first-class suite definition.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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":{"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite Id"},"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"},"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite 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/suites/{suite_id}/run":{"post":{"tags":["Simulations"],"summary":"Run Simulation Suite","description":"Run a first-class suite definition.","operationId":"run-simulation-suite","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"suite_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Suite Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunSimulationBenchmarkRequest"}}}},"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"}}}}}}}}}
```

## 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://platform.api-us.concurrence.com","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"},"error":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Error"},"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"}}]}}}}
```

## Get Simulation Suite Run Results

> Fetch aggregate results for a durable suite run.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","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":{"SimulationSuiteRunResultsResponse":{"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"},"suite_run_id":{"type":"string","format":"uuid","title":"Suite Run Id"},"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite Id"},"summary":{"$ref":"#/components/schemas/SimulationSuiteRunSummary"}},"type":"object","required":["run_ids","total_runs","suite_run_id","summary"],"title":"SimulationSuiteRunResultsResponse"},"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"},"error":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Error"},"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"},"SimulationSuiteRunSummary":{"properties":{"suite_run_id":{"type":"string","format":"uuid","title":"Suite Run Id"},"suite_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Suite Id"},"run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Run Ids"},"total_runs":{"type":"integer","title":"Total Runs"},"expected_case_count":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Expected Case Count"},"status":{"type":"string","enum":["running","completed","failed"],"title":"Status"},"status_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Status Counts"},"case_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Case Ids"},"total_sessions":{"type":"integer","title":"Total Sessions","default":0},"total_turns":{"type":"integer","title":"Total Turns","default":0},"tags":{"items":{"type":"string","maxLength":128},"type":"array","title":"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"}},"type":"object","required":["suite_run_id","run_ids","total_runs","status"],"title":"SimulationSuiteRunSummary"},"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/suite-runs/{suite_run_id}":{"get":{"tags":["Simulations"],"summary":"Get Simulation Suite Run Results","description":"Fetch aggregate results for a durable suite run.","operationId":"get-simulation-suite-run-results","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"suite_run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Suite Run Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationSuiteRunResultsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## 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://platform.api-us.concurrence.com","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"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/api-reference/readme/platform/simulations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.