API Gateway Reference

The API Gateway is the central REST API for Zeq OS. It provides access to the operator registry, computation engine, and service health.

Base URL: /api/ Authentication: API key via X-API-Key header or Authorization: Bearer <key> Rate Limit: 100 requests/minute (configurable via RATE_LIMIT_RPM) Swagger Docs: /api-docs

Authentication

All /api/* endpoints require an API key (except /api/v1/status and /api-health).

# Using X-API-Key header
curl -H "X-API-Key: your-key" http://your-domain/api/v1/operators/all

# Using Authorization header
curl -H "Authorization: Bearer your-key" http://your-domain/api/v1/operators/all

API keys are configured via the ZEQ_API_KEYS environment variable (comma-separated for multiple keys).

Endpoints

Health

GET /api-health

No authentication required. Returns API Gateway health status.

{
  "status": "ok",
  "service": "zeq-api-gateway",
  "version": "1.287.5",
  "uptime": 86400
}

GET /api/v1/status

No authentication required. Returns extended status with operator and service information.

{
  "status": "ok",
  "operators": 1576,
  "categories": 64,
  "version": "6.3.0",
  "pulse": {
    "frequency": 1.287,
    "zeqond": 0.777
  }
}

Operators

GET /api/v1/operators/all

Returns all 1,576 operators. Unauthenticated requests return metadata only (id, name, description, category). Authenticated requests include the equation and equationLaTeX fields.

Response (unauthenticated):

{
  "total": 1576,
  "operators": [
    {
      "id": "KO1",
      "category": "kinematic",
      "description": "Position (1D linear motion)"
    }
  ]
}

Response (authenticated — includes equations):

{
  "total": 1576,
  "operators": [
    {
      "id": "KO1",
      "category": "kinematic",
      "description": "Position (1D linear motion)",
      "equation": "x(t) = x_0 + v_0*t + 0.5*a*t^2",
      "equationLaTeX": "x(t) = x_0 + v_0 t + \\frac{1}{2}at^2"
    }
  ]
}

GET /api/v1/operators/category/:category

Filter operators by category.

curl -H "X-API-Key: $KEY" http://your-domain/api/v1/operators/category/quantum

Response:

{
  "category": "quantum",
  "count": 30,
  "operators": [...]
}

GET /api/v1/operators/search?q=:query

Full-text search across operator IDs and descriptions.

curl -H "X-API-Key: $KEY" "http://your-domain/api/v1/operators/search?q=tunneling"

GET /api/v1/operators/:id

Get a single operator by ID.

curl -H "X-API-Key: $KEY" http://your-domain/api/v1/operators/KO42

GET /api/v1/categories

List all 64 categories with operator counts.

{
  "categories": [
    { "name": "quantum", "count": 30 },
    { "name": "kinematic", "count": 100 },
    { "name": "relativity", "count": 20 }
  ]
}

Computation

POST /api/v1/process

Run a physics query through the 7-Step Wizard Protocol.

Request:

{
  "query": "Calculate gravitational time dilation at r=10km from Earth",
  "domain_hints": ["relativity"],
  "precision": 0.001
}

Response:

{
  "state": {
    "query": "Calculate gravitational time dilation at r=10km from Earth",
    "domains": ["relativity"],
    "selected_operators": ["KO42", "GR31", "GR35"],
    "operator_count": 3,
    "master_sum": 0.998847,
    "phase_coherence": 0.042,
    "zeqond": 3296847201,
    "phase": 0.4521,
    "precision_met": true
  }
}

Sync

GET /sync/health

Sync Engine health status.

WebSocket /ws

Connect to the HulyaPulse WebSocket stream. Receives tick events at 1.287 Hz.

const ws = new WebSocket('ws://your-domain/ws');
ws.onmessage = (event) => {
  const tick = JSON.parse(event.data);
  console.log(`Zeqond: ${tick.zeqond}, Phase: ${tick.phase}`);
};

Tick format:

{
  "type": "tick",
  "zeqond": 3296847201,
  "phase": 0.4521,
  "timestamp": 1740499200.123,
  "ko42": 0.000891
}

Error Responses

Status	Meaning
400	Bad request — invalid query or parameters
401	Unauthorized — missing or invalid API key
404	Not found — operator or endpoint doesn't exist
429	Rate limited — too many requests
500	Internal server error

{
  "error": "Unauthorized",
  "message": "Valid API key required. Set X-API-Key header."
}

Rate Limiting

Default: 100 requests per minute per IP. Configurable via RATE_LIMIT_RPM environment variable.

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1740499260