GiuliaAPI Documentation

Overview

GiuliaAPI is designed for AI agents that need to inspect, modify, run, and evaluate radio network simulations. It provides a human-readable REST interface, machine-readable tool schemas, and an MCP endpoint for clients that support tool calling through the Model Context Protocol.

Based on OpenGiuliaSLS

GiuliaAPI is built on top of the open-source OpenGiuliaSLS project. OpenGiuliaSLS provides the underlying radio network simulation engine; GiuliaAPI adds an agent-friendly service layer around it, including HTTP endpoints, MCP tool schemas, workspace lifecycle management, quotas, and usage instrumentation.

This separation is intentional: OpenGiuliaSLS remains the simulation core, while GiuliaAPI focuses on making that core usable by external agents, applications, scripts, and notebooks.

Core Concepts

Authentication

Authenticated deployments expect an API key in the X-API-Key header. For simple workflows, GiuliaAPI creates or reuses a workspace automatically. Advanced clients may pass X-Workspace-ID explicitly to select a specific workspace.

API Key Permissions

API keys can be configured with different permissions depending on the deployment. A key may be allowed to create workspaces, run simulations, inspect results, or all of these.

• Workspace permissions: create, inspect, list, or delete workspaces.
• Simulation permissions: create simulations, update parameters, run simulations, and read results.

REST Quickstart

curl

BASE="https://nicopi-giuliaapi.hf.space"
API_KEY="your-api-key"

SIM_ID=$(curl -s -X POST "$BASE/api/create_simulation" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scenario_model":"ITU_R_M2135_UMa","ue_distribution":"uniform","link_direction":"downlink","number_of_episodes":1}' \
  | python -c "import sys,json; print(json.load(sys.stdin)['sim_id'])")

curl -s -X POST "$BASE/api/run_simulation" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"sim_id\":\"$SIM_ID\"}"

Python

import requests

base = "https://nicopi-giuliaapi.hf.space"
headers = {"X-API-Key": "your-api-key"}

# Create a simulation in your API-key workspace.
sim = requests.post(f"{base}/api/create_simulation", headers=headers, json={
    "scenario_model": "ITU_R_M2135_UMa",
    "ue_distribution": "uniform",
    "link_direction": "downlink",
    "number_of_episodes": 1,
}).json()

# Run the latest simulation in that workspace.
requests.post(f"{base}/api/run_simulation", headers=headers)

# Read aggregated results from the latest simulation.
results = requests.post(f"{base}/api/get_aggregated_results", headers=headers, json={
    "kpis": ["ue_throughput_Mbps"],
    "group_by": "all",
    "metrics": ["mean"],
}).json()
print(results)

MCP

The MCP endpoint is available at /mcp. It exposes Giulia simulation operations as tools using JSON-RPC over the MCP transport.

MCP clients generally call initialize, then tools/list, then tools/call. Workspace binding is handled by headers, transport session metadata, or server-side binding. Tool arguments should describe the simulation operation, not workspace management.

Usage Counters

GiuliaAPI records workspace-level counters so clients can monitor API usage and simulation activity.

Endpoint Reference