API References

The Stage-X control plane exposes robust, high-performance REST APIs for programmatic actuation. All endpoints are guarded by strict rate-limiting (via Upstash Redis) and require mutual TLS (mTLS) for authentication in physical deployments.

Base URL

https://api.stage-x.space/v1

All API requests must include the Authorization: Bearer <API_KEY> header. For sovereign deployments, replace with mTLS client certificate authentication.

Rate Limits

Tier	Requests/sec	Burst
Free	10	50
Pro	1,000	5,000
Enterprise (Sovereign)	Unlimited	N/A

POST/api/dispatch

V1.0.0

The central dispatch controller for the Antigravity multi-agent orchestrator. This endpoint ingests raw sensor telemetry or explicit actuation requests, validates thermodynamic boundaries, and routes the task to the optimal edge node. The dispatch engine evaluates the metabolic cost of each candidate node and selects the one that minimizes total system entropy while meeting the requested latency SLA.

Request Headers

Content-Type: application/json
Authorization: Bearer <API_KEY>
X-Idempotency-Key: <UUID>
X-Request-Priority: CRITICAL | HIGH | LOW

Request Body (application/json)

{
  "payload": {
    "sensor_id": "string (UUID)",
    "timestamp": "ISO8601",
    "metrics": {
      "temperature_celsius": "float",
      "acoustic_resonance_hz": "float",
      "vram_utilization": "float",
      "power_draw_watts": "float",
      "vibration_amplitude_g": "float"
    },
    "priority": "enum (LOW | HIGH | CRITICAL)",
    "target_latency_ms": "integer (optional, default: 100)",
    "callback_url": "string (optional, webhook for async results)"
  },
  "context": {
    "deployment_id": "string (UUID)",
    "region": "string (e.g. us-east-1)",
    "air_gapped": "boolean"
  },
  "signature": "string (HMAC-SHA256)"
}

Response (202 Accepted)

{
  "dispatch_id": "dsp-a7c3e9f1-4b2d-4e8a-9c6f-1d3e5f7a9b0c",
  "status": "QUEUED",
  "estimated_completion_ms": 847,
  "assigned_node": "node-sovereign-03",
  "metabolic_cost_watts": 2847.3,
  "created_at": "2026-07-05T11:30:00.000Z"
}

Response Codes

Status	Description
202 Accepted	Payload validated and dispatched to swarm. Returns a `dispatch_id` for tracking.
400 Bad Request	Malformed payload or missing required fields. Response body includes field-level validation errors.
401 Unauthorized	Invalid cryptographic signature or missing mTLS certificate.
429 Too Many Requests	Rate limit exceeded. `Retry-After` header indicates backoff duration.
503 Service Unavailable	All sovereign nodes are thermally throttled or offline. Retry with exponential backoff.

POST/api/contact

V1.0.0

CRM ingestion endpoint for the Forward Deploy Enterprise AI Summit. Processes VIP registration manifests, assigns priority routing tiers, and triggers automated email sequences via Resend.

Request Body (application/json)

{
  "name": "string (required)",
  "email": "string (required, valid email)",
  "company": "string (required)",
  "role": "string (required)",
  "intent": "string (optional)",
  "referral_code": "string (optional)",
  "preferred_event": "string (e.g. bengaluru, dubai)"
}

Response (201 Created)

{
  "contact_id": "cnt-e4a2b8c6-1f3d-4a7e-b9c5-2d4f6a8e0b1c",
  "tier": "VIP | GENERAL",
  "confirmation_sent": true,
  "event": "bengaluru"
}

GET/api/telemetry

V1.0.0

Retrieves real-time telemetry snapshots from sovereign edge nodes. Returns GPU temperatures, VRAM utilization, token throughput, power draw, and acoustic sensor readings. Supports WebSocket upgrade for continuous streaming via the Upgrade: websocket header.

Query Parameters

Param	Type	Description
node_id	string	Filter by specific sovereign node UUID
window	string	Time window: `1m`, `5m`, `1h`, `24h`
metrics	string[]	Comma-separated list: `gpu_temp,vram,throughput,power`

Response (200 OK)

{
  "node_id": "node-sovereign-03",
  "snapshots": [
    {
      "timestamp": "2026-07-05T11:30:00.000Z",
      "gpu_temp_celsius": 72.4,
      "vram_utilization_pct": 87.2,
      "token_throughput_per_sec": 4218,
      "power_draw_watts": 2847.3,
      "acoustic_resonance_hz": 440.0
    }
  ],
  "sampling_rate_hz": 100,
  "window": "5m"
}

GET/api/deployments

V1.0.0

Lists all active sovereign deployments across regions. Returns deployment metadata including model configuration, GPU allocation, VPC CIDR ranges, health status, and real-time performance metrics. Supports pagination and filtering by status, region, and provider.

Query Parameters

Param	Type	Description
status	string	Filter: `Active`, `Provisioning`, `Air-Gapped`, `Failed`
region	string	Cloud region (e.g. `us-east-1`, `eu-west-1`)
page	integer	Page number (default: 1, max page size: 50)

Response (200 OK)

{
  "deployments": [
    {
      "id": "dep-a1b2c3d4",
      "name": "sovereign-prod-east",
      "model": "Llama 3.1 405B",
      "provider": "GCP",
      "region": "us-east-1",
      "status": "Active",
      "gpu_type": "H100 80GB SXM5",
      "gpu_count": 8,
      "vpc_cidr": "10.0.0.0/16",
      "token_throughput": 4218,
      "latency_ms": 12,
      "cost_per_hour": 32.40
    }
  ],
  "total": 12,
  "page": 1,
  "page_size": 50
}

GET/api/audit-log

V1.0.0

Retrieves the immutable audit trail for a deployment. Returns chronologically-ordered entries covering data-residency checks, PII scrubbing events, policy violations, access audits, and encryption verification. Each entry includes a Merkle proof for independent verification of log integrity.

Query Parameters

Param	Type	Description
deployment_id	string	Required. The UUID of the sovereign deployment.
severity	string	Filter: `info`, `warning`, `critical`
type	string	Event type: `data-residency`, `pii-scrub`, `policy-violation`, `access-audit`
since	ISO8601	Return entries after this timestamp

Response (200 OK)

{
  "entries": [
    {
      "id": "aud-f8e7d6c5",
      "timestamp": "2026-07-05T11:29:47.123Z",
      "type": "data-residency",
      "severity": "info",
      "message": "Data residency check passed for VPC 10.0.0.0/16",
      "resource": "dep-a1b2c3d4",
      "region": "us-east-1",
      "status": "passed",
      "merkle_proof": "0x7a3f..."
    }
  ],
  "total": 847,
  "has_next_page": true,
  "cursor": "eyJsYXN0X2lkIjoi..."
}

SDK & Libraries

Official client libraries are available for direct integration with the Stage-X control plane. All SDKs implement automatic retry with exponential backoff, request signing, and type-safe request/response models.

Python

pip install stagex-sdk

Python 3.10+ · asyncio native · Pydantic v2 models

Node.js

npm install @stagex/sdk

Node 20+ · TypeScript native · Zod schemas

go get stagex.space/sdk

Go 1.22+ · context-aware · zero dependencies

Changelog

v1.0.0 — July 2026

Initial public release. Core dispatch API, telemetry streaming, audit log endpoints. Python, Node.js, and Go SDKs.

v0.9.0 — June 2026

Beta release. Added air-gapped deployment support, acoustic routing protocol, and thermodynamic load balancer integration.

v0.8.0 — May 2026

Alpha release. Internal testing with select enterprise partners. Core sovereign node provisioning and mTLS authentication.