# Simetrix API Reference (Condensed)

```bash
# Hosted API base URL
API_BASE="https://api.simetrix.io"

# OpenAPI UI for the full schema
# (Use this for exact field definitions and response models)
echo "$API_BASE/api-docs"
```

## Authentication
- Preferred: Authorization: Bearer <token>
- Accepted on some routes: X-API-Key or x-pt-key headers
- Common scopes: forecast:read:v2, portfolio:read, scenario:run, scenario:condition, admin

## Core Endpoints (public)
- POST /simulate
- GET /simulate/{run_id}
- GET /simulate/{run_id}/artifact
- GET /v2/forecast/* (symbol, portfolio, conditioned)
- GET /analytics/* (summary, telemetry)
- GET /copilot/tools/* (scenario, portfolio, events)
- GET /public/attestations
- GET /metrics
- GET /api-docs

## /simulate request contract (key fields)
- symbol (string): ticker, e.g. "X:NVDA"
- horizon_days (int): forecast horizon
- n_paths (int): requested path count
- timespan (day|hour|min): step basis
- profile (quick|deep): compute tier
- engine (jd|heston|hybrid): engine selector
- include_news/include_options/include_futures (bool)
- x_handles (list): optional social handles
- seed (int, optional)

## Guardrails and errors
- 401: missing or invalid auth (admin_required, invalid_admin_session, etc.)
- 403: scope or plan restriction
- 410: deprecated legacy endpoints
- 429: quota or rate limit hit
- 5xx: upstream dependency failure or internal error

## Example: launch a simulation run

```bash
# Launch a simulation run
curl -X POST "$API_BASE/simulate" \
  -H "Authorization: Bearer $SIMETRIX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "X:NVDA",
    "horizon_days": 45,
    "n_paths": 5000,
    "profile": "deep",
    "timespan": "day",
    "include_news": true,
    "include_options": true,
    "include_futures": true,
    "engine": "hybrid"
  }'
```

## Example: poll status and fetch artifact

```bash
# Replace with the run_id returned by /simulate
RUN_ID="run_abc123"

# Poll run status
curl -H "Authorization: Bearer $SIMETRIX_API_TOKEN" \
  "$API_BASE/simulate/$RUN_ID"

# Fetch the artifact when ready
curl -H "Authorization: Bearer $SIMETRIX_API_TOKEN" \
  "$API_BASE/simulate/$RUN_ID/artifact"
```

## SDK quick reference (Python)

```python
# pip install simetrix-sdk
from simetrix_sdk import SimetrixClient

# Create an authenticated client
client = SimetrixClient(token="YOUR_API_TOKEN")

# Symbol forecast
forecast = client.forecast_symbol("X:NVDA", horizon_days=45)

# Launch and fetch a simulation
run = client.launch_simulation({"symbol": "X:NVDA", "mode": "quick", "horizon_days": 45})
artifact = client.get_simulation_artifact(run["run_id"])
```

## More docs
- Full OpenAPI schema: https://api.simetrix.io/api-docs
- Guides: https://simetrix.io/docs/contexts/guides.md