Developer reference
REST API
GiuliaAPI REST calls are simulation-first. Create a simulation with your API key; GiuliaAPI creates or reuses a workspace automatically and later routes calls by sim_id.
Public deployment: the hosted endpoint is intended for agent interaction and experimentation, not high-throughput batch jobs.
Request Headers
| Header | Required | Description |
|---|---|---|
X-API-Key | Yes, on authenticated deployments | Authenticates the caller and applies configured permissions and quotas. |
X-Workspace-ID | No, for simple workflows | Optional advanced header used to select a specific workspace when multiple workspaces are active. |
Content-Type: application/json | Yes, for JSON requests | Used on POST requests with JSON request bodies. |
Simple Simulation Lifecycle
| Step | Endpoint | What happens |
|---|---|---|
| 1 | POST /api/create_simulation | Creates or reuses a workspace automatically and returns workspace_id plus sim_id. |
| 2 | POST /api/run_simulation | Routes by sim_id; X-Workspace-ID is not needed in simple mode. |
| 3 | POST /api/get_aggregated_results | Routes by sim_id and returns compact KPI statistics. |
Workspace Lifecycle
These management endpoints may require operator permissions. Normal clients can use automatic workspace selection; see workspaces and lifecycle.
Workspace endpoints are available for advanced clients that need explicit lifecycle control, grouping, counters, or multiple active workflows.
| Method | Endpoint | Parameters | Returns |
|---|---|---|---|
| POST | /api/create_workspace | Optional max_calls to cap counted API calls in the workspace. | workspace_id, expiry information, and call limit. |
| GET | /api/workspaces/{workspace_id} | Path parameter workspace_id. | Workspace metadata, counters, and active simulation count. |
| GET | /api/workspaces | None. | List of active workspaces visible to the caller. |
| DELETE | /api/workspaces/{workspace_id} | Path parameter workspace_id. | Deletion status. |
Simulation Lifecycle
| Method | Endpoint | Key Parameters | Returns |
|---|---|---|---|
| POST | /api/create_simulation | scenario_model, ue_distribution, link_direction, optional number_of_episodes, number_of_steps. | sim_id and any evicted_sim_ids. |
| POST | /api/load_scenario | scenario_id, for pre-configured scenarios. | sim_id loaded from the scenario. |
| POST | /api/list_simulations | None. | Retained simulations and the latest sim_id. |
| POST | /api/clone_simulation | Optional source_sim_id, optional number_of_episodes. | New editable sim_id. |
| POST | /api/delete_simulation | Optional sim_id; omitted means latest simulation. | Deleted sim_id. |
Parameters, Execution, Results
| Endpoint | Purpose | Detailed Docs |
|---|---|---|
POST /api/get_engineering_parameters | Read cell and site engineering values. | Parameter Catalog |
POST /api/set_engineering_parameter | Set one writable engineering parameter before running. | Parameter Catalog |
POST /api/get_carrier_management_config | Read per-cell roles, pairings, and carrier shutdown settings. | Tool Parameters |
POST /api/set_carrier_management_config | Update carrier-management settings on one or more cells before running. | Tool Parameters |
POST /api/get_ue_parameters | Read UE deployment and UE-side fields. | Parameter Catalog |
POST /api/set_ue_parameter | Override one writable UE parameter before running. | Parameter Catalog |
POST /api/run_simulation | Execute a configured simulation. | Tool Parameters |
POST /api/get_results | Return raw KPI arrays. | KPI Catalog |
POST /api/get_aggregated_results | Return compact aggregate KPI statistics. | KPI Catalog |
Complete examples
Follow the Python quickstart for a create → run → read workflow.
Machine-readable schemas
OpenAPI schema describes HTTP routes and request models. Tool schemas are available at /tools, /tools/openai, /tools/anthropic, and /tools/text. Availability and authentication depend on the deployment.