# Voice Simulation

The voice simulation (VoiceSim) API lets you systematically explore how voice configuration parameters affect call quality. Create simulation runs, sample configuration points, evaluate them against built-in scenarios, and retrieve scored results.

{% hint style="info" %}
**Conceptual overview**: For background on what VoiceSim does and why, see the [Voice Simulation](https://docs.amigo.ai/testing/voice-simulation) conceptual documentation.
{% endhint %}

## Endpoints

All endpoints are scoped to a workspace and require a workspace API key.

### Create Simulation Run

|             |                                                               |
| ----------- | ------------------------------------------------------------- |
| **Method**  | `POST`                                                        |
| **Path**    | `/v1/{workspace_id}/sims`                                     |
| **Auth**    | Workspace API key                                             |
| **Returns** | Created run with ID, status, and configuration space metadata |

Creates a new simulation run. The run is initialized with the platform's default 18-dimension configuration space and built-in scenario set.

### List Simulation Runs

|             |                                      |
| ----------- | ------------------------------------ |
| **Method**  | `GET`                                |
| **Path**    | `/v1/{workspace_id}/sims`            |
| **Auth**    | Workspace API key                    |
| **Query**   | `limit` (default 20, max 100)        |
| **Returns** | Paginated list of runs, newest first |

### Evaluate a Configuration Point

|            |                                             |
| ---------- | ------------------------------------------- |
| **Method** | `POST`                                      |
| **Path**   | `/v1/{workspace_id}/sims/{run_id}/evaluate` |
| **Auth**   | Workspace API key                           |

#### Request Body

| Field           | Type         | Description                                                                                                                             |
| --------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `point_indices` | array of int | Configuration point as dimension indices. Length must match space dimensions (18). Each index must be within the dimension's bin range. |
| `scenario_name` | string       | Name of the scenario to evaluate against (e.g., `greeting_barge_in`, `crisis_at_10`)                                                    |

#### Response

Returns the evaluation result with composite score, individual penalty breakdown, and adapter log.

### Sample and Evaluate Multiple Points

|            |                                           |
| ---------- | ----------------------------------------- |
| **Method** | `POST`                                    |
| **Path**   | `/v1/{workspace_id}/sims/{run_id}/sample` |
| **Auth**   | Workspace API key                         |

#### Request Body

| Field      | Type | Description                                                           |
| ---------- | ---- | --------------------------------------------------------------------- |
| `n_points` | int  | Number of configuration points to sample via Latin Hypercube Sampling |

Samples `n_points` configurations uniformly across the space and evaluates each against all scenarios. Results are persisted and available via the points endpoint. Publishes SSE events for live progress tracking.

### Get Simulation Run

|             |                                                                   |
| ----------- | ----------------------------------------------------------------- |
| **Method**  | `GET`                                                             |
| **Path**    | `/v1/{workspace_id}/sims/{run_id}`                                |
| **Auth**    | Workspace API key                                                 |
| **Returns** | Run status, best results so far, and configuration space metadata |

### Get Run Summary

|            |                                            |
| ---------- | ------------------------------------------ |
| **Method** | `GET`                                      |
| **Path**   | `/v1/{workspace_id}/sims/{run_id}/summary` |
| **Auth**   | Workspace API key                          |

Returns an aggregated summary computed server-side:

| Field               | Description                                                              |
| ------------------- | ------------------------------------------------------------------------ |
| `best_per_scenario` | Highest-scoring configuration for each scenario                          |
| `penalty_frequency` | Penalty types sorted by frequency across all evaluations                 |
| `config_diff`       | Dimensions where the best configuration differs from production defaults |

### List Scored Points

|             |                                                                                                                              |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Method**  | `GET`                                                                                                                        |
| **Path**    | `/v1/{workspace_id}/sims/{run_id}/points`                                                                                    |
| **Auth**    | Workspace API key                                                                                                            |
| **Query**   | `scenario` (optional filter), `limit` (default 50, max 200), `order_by` (`score` for best-first or `time` for chronological) |
| **Returns** | List of scored configuration points with composite scores and penalty details                                                |

### Complete Simulation Run

|            |                                             |
| ---------- | ------------------------------------------- |
| **Method** | `POST`                                      |
| **Path**   | `/v1/{workspace_id}/sims/{run_id}/complete` |
| **Auth**   | Workspace API key                           |

Marks the run as finished. Ephemeral database branches used for write isolation are cleaned up.

## Network Information

### Get Egress IPs

|            |                                         |
| ---------- | --------------------------------------- |
| **Method** | `GET`                                   |
| **Path**   | `/v1/{workspace_id}/network/egress-ips` |
| **Auth**   | Workspace API key (any role)            |

Returns the platform's static IP addresses used for all outbound traffic. Add these to your firewall allowlist to enable data source connectivity (EHR, CRM, FHIR stores).

#### Response

| Field        | Type            | Description                     |
| ------------ | --------------- | ------------------------------- |
| `egress_ips` | array of string | Static NAT gateway IP addresses |
| `region`     | string          | Deployment region               |
| `note`       | string          | Usage guidance                  |