NEURAX API Reference

neurax-service is a production actix‑web HTTP server (default 0.0.0.0:9098) exposing 38 REST routes with CORS, gzip compression, and authentication via Supabase JWT or API keys.

Base URL

http://localhost:9098

Authentication

Two authentication methods are supported:

1. Supabase JWT (Web UI Users)

Pass a valid Supabase access token in the Authorization header:

Authorization: Bearer <supabase-jwt>

2. API Keys (Programmatic Access)

Pass an API key (prefixed with nrx_) in either the X-API-Key header or the Authorization: Bearer header:

X-API-Key: nrx_<64-hex-chars>

API Key Scopes

Error Codes

Endpoint Summary

System

Analysis

Inference

Time Machine

Export

Presets

Hardware

Projects

Credits & Billing

Compliance

API Keys

Agent Control (API Key Auth)

Plugin

Endpoint Details

GET /health

Health check endpoint. No authentication required.

Response 200 OK:

{
  "status": "ok"
}

POST /analyze

Run the full 10‑pass analytical pipeline on a model configuration.

Request Body:

{
  "topology": {
    "schema_version": "1.0",
    "model": {
      "name": "MyModel",
      "type": "transformer",
      "global_params": {
        "num_layers": 12,
        "sequence_length": 2048,
        "vocab_size": 50257,
        "embedding_dim": 768
      },
      "layers": [
        {
          "id": "layer_1",
          "layer_type": "embedding",
          "params": {
            "vocab_size": 50257,
            "embedding_dim": 768
          }
        }
      ]
    },
    "training": {
      "batch_size": 128,
      "max_steps": 100000
    },
    "hardware": {
      "gpus": [
        {"name": "A100-SXM", "count": 8}
      ]
    }
  }
}

Response 200 OK:

{
  "report": {
    "model_name": "MyModel",
    "total_parameters": 125000000,
    "total_flops": 2.5e17,
    "peak_vram_bytes": 42000000000,
    "training_cost_usd": 45000.00,
    "training_time_hours": 120.5,
    "energy_kwh": 15000.0,
    "co2_kg": 4500.0,
    "metrics": { },
    "diagnostics": [ ],
    "phase_timeline": [ ]
  }
}

Error Responses:

POST /analyze/stream

Start a streaming analysis job. Returns a job ID for SSE streaming.

Request Body (same as /analyze).

Response 200 OK:

{
  "job_id": "abc123-...",
  "status": "running"
}

GET /analyze/stream/{job_id}

Stream Server‑Sent Events for a running analysis job.

Response text/event-stream:

event: phase
data: {"phase": "Architecture", "status": "running", "progress": 10}

event: metric
data: {"name": "total_parameters", "value": 125000000, "unit": "params"}

event: done
data: {"job_id": "abc123-...", "status": "completed"}

GET /analyze/result/{job_id}

Retrieve the completed analysis report for a job.

Response 200 OK:

{
  "job_id": "abc123-...",
  "status": "completed",
  "report": { }
}

POST /analyze/compare

Compare up to 8 hardware configurations for the same model.

Request Body:

{
  "topology": { },
  "configs": [
    {
      "hardware": "H100-SXM",
      "gpu_count": 8,
      "precision": "fp16",
      "gpu_memory_gb": 80,
      "gpu_bandwidth_gbs": 3352.0
    },
    {
      "hardware": "A100-SXM",
      "gpu_count": 8,
      "precision": "bf16",
      "gpu_memory_gb": 80,
      "gpu_bandwidth_gbs": 2039.0
    }
  ]
}

Response 200 OK:

{
  "results": [
    {
      "label": "8 × H100-SXM @ fp16",
      "report": { }
    },
    {
      "label": "8 × A100-SXM @ bf16",
      "report": { }
    }
  ]
}

POST /inference/simulate

Simulate inference behavior for a model configuration.

Request Body:

{
  "topology": { },
  "params": {
    "model_name": "MyModel",
    "num_layers": 12,
    "d_model": 768,
    "num_heads": 12,
    "seq_len": 2048,
    "vocab_size": 50257,
    "batch_size": 1,
    "precision": "fp16",
    "hardware": "A100-SXM"
  }
}

Response 200 OK:

{
  "report": {
    "model_name": "MyModel",
    "stability_index": 0.85,
    "hallucination_risk": 0.12,
    "sampling_volatility": 0.05,
    "latency_ms": 12.5,
    "throughput_tokens_per_s": 800.0
  }
}

POST /timemachine

Multi‑year cost/carbon projection.

Request Body:

{
  "topology": { },
  "years": 5,
  "hardware_growth_rate": 0.15,
  "energy_cost_per_kwh": 0.12,
  "carbon_intensity_g_per_kwh": 475
}

Response 200 OK:

{
  "projections": [
    {
      "year": 2026,
      "training_cost_usd": 45000.0,
      "energy_kwh": 15000.0,
      "co2_kg": 4500.0
    }
  ],
    "compliance": { }
}

POST /export/onnx

Export a model topology to ONNX binary format.

Request Body:

{
  "topology": { },
  "model_name": "MyModel"
}

Response 200 OK:

{
  "data": "<base64-encoded-onnx-protobuf>",
  "model_name": "MyModel",
  "node_count": 12
}

POST /export/github

Push model files to a GitHub repository and optionally create a pull request.

Request Body:

{
  "topology": { },
  "github_token": "<personal-access-token>",
  "owner": "username",
  "repo": "repo-name",
  "branch": "main",
  "create_pr": true,
  "pr_title": "Add MyModel architecture",
  "pr_body": "Auto-generated by NEURAX"
}

Response 200 OK:

{
  "success": true,
  "commit_sha": "abc123...",
  "pr_url": "https://github.com/username/repo-name/pull/1"
}

GET /projects

List all projects for the authenticated user.

Response 200 OK:

[
  {
    "id": "proj_123",
    "name": "My Project",
    "description": "A transformer model",
    "topology": { },
    "created_at": "2026-07-24T10:00:00Z",
    "updated_at": "2026-07-24T10:00:00Z"
  }
]

POST /projects

Create a new project.

Request Body:

{
  "name": "My Project",
  "description": "A transformer model",
  "topology": { }
}

Response 200 OK:

{
  "id": "proj_123",
  "name": "My Project",
  "description": "A transformer model",
  "topology": { },
  "created_at": "2026-07-24T10:00:00Z",
  "updated_at": "2026-07-24T10:00:00Z"
}

GET /credits

Get the current user’s credit balance and plan information.

Response 200 OK:

{
  "credits": {
    "used": 150,
    "limit": 1000,
    "plan": "elite",
    "period_start": "2026-07-01T00:00:00Z",
    "period_end": "2026-08-01T00:00:00Z"
  }
}

GET /compliance/config

Get regulatory compliance configuration (EU AI Act, CSRD, DSA).

Response 200 OK:

{
  "eu_ai_act": { },
  "csrd": { },
  "dsa": { }
}

API Key Management

POST /api-keys

Create a new API key.

Request Body:

{
  "name": "My API Key",
  "scopes": ["analyze", "inference", "export"]
}

Response 200 OK:

{
  "key": "nrx_abc123...",
  "name": "My API Key",
  "user_id": "user_123",
  "created_at": "2026-07-24T10:00:00Z",
  "active": true,
  "scopes": ["analyze", "inference", "export"]
}

GET /api-keys

List all API keys for the current user.

POST /api-keys/{key_id}/revoke

Revoke (deactivate) an API key.

DELETE /api-keys/{key_id}

Delete (permanently remove) an API key.

POST /plugin/validate

Validate a plugin architecture specification.

Request Body:

{
  "topology": { }
}

Response 200 OK:

{
  "valid": true,
  "warnings": [],
  "errors": []
}

Python Agent API

The neurax-agent (FastAPI, port 8099) provides a separate API for AI‑driven architecture design.

POST /runs

Start a new agent run. The agent uses an LLM (OpenAI or Anthropic) to plan, validate, and materialize an architecture.

Request Body:

{
  "user_message": "Design a transformer model with 12 layers for text classification",
  "snapshot": {
    "family": "transformer",
    "nodes": [],
    "connections": [],
    "groups": [],
    "allowed_layer_types": [],
    "allowed_families": ["transformer", "cnn", "moe"],
    "catalogue_id": null,
    "catalogue": [],
    "missing_mandatory_fields": [],
    "hw_config": {},
    "analysis_warnings": []
  },
  "creativity": 0.3
}

Response 200 OK:

{
  "run_id": "abc123-..."
}

GET /runs/{run_id}/events

Stream Server‑Sent Events for an agent run.

Response text/event-stream:

event: assistant
data: {"content": "I'll design a transformer architecture for you..."}

event: tool
data: {"name": "add_node", "args": {"id": "input", "type": "input", "params": {}}}

event: done
data: {}

GET /health

Agent health check.

Response 200 OK:

{
  "status": "ok"
}

CLI Interface

The neurax CLI provides command‑line access to the core analysis pipeline.

# Analyze a model and generate a report
neurax analyze model.json -o report.md

# Analyze with JSON output
neurax analyze model.json -f json -o report.json

# Validate a JSON model configuration
neurax validate model.json

# Show a quick summary of the model
neurax summary model.json

# Full compilation: validate → analyze → generate MLIR
neurax compile model.json -o output/

# Show version
neurax version

Compile Output

The compile command generates:

MCP Server

The neurax-mcp package provides a Model Context Protocol server that exposes NEURAX capabilities to MCP‑compatible clients (e.g., Claude Desktop).

Available Tools