Nexus Integration Guide

Sending an API Key

All protected endpoints require an API key. Two methods are accepted:

Method A — Header (preferred)

GET /orgs HTTP/1.1
Host: api.nexus-dev.codezerogroup.com
X-API-Key: your-api-key-here

# curl example

curl https://api.nexus-dev.codezerogroup.com/orgs \
  -H "X-API-Key: your-api-key-here"

Method B — Query Parameter

Required for EventSource / SSE connections which cannot set custom headers.

GET /pipelines/{id}/runs/{run_id}/events?api_key=your-api-key-here

Error Responses

Bootstrap Key

On the first call to any protected endpoint when the key database is empty, the engine imports the WORMWOOD_API_KEY environment variable as a full-privilege key with client_id=bootstrap. This is the initial admin key for a fresh deployment.

Public Endpoints (no key required)

Create a Key

POST /orgs/{org_slug}/api-keys
X-API-Key: <admin-key>
Content-Type: application/json

{
  "label": "ci-pipeline",
  "scopes": ["read", "execute"]
}

Response includes api_key (raw value, returned once only), key_id, label, scopes, created_at.

List Keys

GET /orgs/{org_slug}/api-keys

Returns key metadata. Raw key values are never returned in list responses.

Rename a Key

PATCH /orgs/{org_slug}/api-keys/{key_id}
Content-Type: application/json

{ "label": "new-label" }

Revoke a Key

DELETE /orgs/{org_slug}/api-keys/{key_id}

Deactivates the key. Requests using a revoked key receive 403.

Create an Organisation

POST /orgs
X-API-Key: <admin-key>
Content-Type: application/json

{
  "slug": "my-org",
  "name": "My Organisation",
  "plan_tier": "enterprise"
}

Team Management

# Create team
POST /orgs/{org_slug}/teams
{ "slug": "ops", "name": "Operations" }

# Add user to team
POST /orgs/{org_slug}/teams/{team_slug}/users
{ "email": "user@example.com", "role": "operator" }

# List users in team
GET /orgs/{org_slug}/teams/{team_slug}/users

# List all users across all teams
GET /orgs/{org_slug}/users

User Roles

Environments

Deployment environments are metadata attached to an org (e.g. dev / staging / prod). Used for pipeline routing context.

POST /orgs/{org_slug}/environments
{ "slug": "prod", "name": "Production", "app_url": "https://app.example.com" }

GET /orgs/{org_slug}/environments
GET /orgs/{org_slug}/environments/{env_slug}

Create a Pipeline

POST /pipelines
X-API-Key: <key>
Content-Type: application/json

{
  "org_slug": "my-org",
  "name": "Intake Form",
  "slug": "intake-form",
  "graph_json": {
    "nodes": [...],
    "edges": [...]
  }
}

Node Types

# List all registered node types
GET /node-types

# Get schema for a specific node type
GET /node-types/{name}

Key node types available in this deployment:

Pipeline Versioning

# Fork active pipeline into new draft (bumps version)
POST /pipelines/{pipeline_id}/fork

# List all versions for a slug
GET /pipelines/history?org_slug={org_slug}&slug={slug}

# Deactivate (active -> archived)
POST /pipelines/{pipeline_id}/deactivate

# Export as self-contained descriptor JSON
GET /pipelines/{pipeline_id}/descriptor

# Import from descriptor
POST /pipelines/import

Canvas Navigation

The engine generates multi-scale canvas layouts for SPAs to render node graphs without layout computation.

# Returns SVG/layout data at 4 zoom scales (overview / mid / detail / full)
GET /pipelines/{pipeline_id}/canvas/{scale}

Node Schema (Chameleon Integration)

Chameleon uses these endpoints to render schema-driven forms for individual nodes.

# Full node schema
GET /pipelines/{pipeline_id}/nodes/{node_id}/schema

# Schema filtered by user role (RBAC)
GET /pipelines/{pipeline_id}/nodes/{node_id}/schema/role

# Dynamic options for a BDT field
GET /pipelines/{pipeline_id}/nodes/{node_id}/bdt/{field_name}/options

Start a Run

POST /pipelines/{pipeline_id}/run
X-API-Key: <key>
Content-Type: application/json

{
  "inputs": {
    "field_a": "value",
    "field_b": 42
  },
  "triggered_by": "user@example.com"
}

Returns a run object with run_id, status (pending / running / suspended / completed / failed), started_at.

Execute (immediate, synchronous for ARC SPA)

POST /pipelines/{pipeline_id}/execute

Executes and returns node outputs directly. Used by the ARC SPA for short-lived validation pipelines.

Run Lifecycle

Generic Execute Endpoint

POST /execute

Low-level executor. Accepts a pipeline graph and inputs inline, without a persisted pipeline record. Used for ad-hoc validation.

• Run reaches HumanGate

  Run status changes to suspended. A token is issued and sent to configured recipients (email / webhook).

• Retrieve pending gates for a role

  GET /orgs/{org_slug}/humangate/pending?role=approver

  Returns all tokens pending approval for the given role within the org.

• Inspect a gate

  GET /approvals/{token}

  Returns gate context: pipeline name, submitter, inputs, resolution options defined in the node schema.

• Approve or Reject

  POST /approvals/{token}/approve
  Content-Type: application/json
  { "comment": "Looks good" }
  
  POST /approvals/{token}/reject
  Content-Type: application/json
  { "comment": "Missing documentation" }

  The run is resumed (on approve) or terminated with failure status (on reject). Token becomes invalid after use.

Run Event Stream

GET /pipelines/{pipeline_id}/runs/{run_id}/events?api_key={key}

Emits events as nodes execute: node_started, node_completed, node_failed, run_completed, run_failed, gate_suspended.

# JavaScript EventSource example
const es = new EventSource(
  `https://api.nexus-dev.codezerogroup.com/pipelines/${pipelineId}/runs/${runId}/events?api_key=${key}`
);
es.onmessage = (e) => {
  const evt = JSON.parse(e.data);
  console.log(evt.type, evt.node_id, evt.status);
};

Global Pipeline Status Stream

GET /pipeline-status-stream?api_key={key}

Emits live status updates for all active pipeline runs across all orgs the key has access to. Used by the Nexus hub dashboard.

Telemetry Stream

GET /run/telemetry/stream?api_key={key}

Emits engine telemetry metrics (CPU, memory, active runs, queue depth) on a fixed interval.

Validate a Payload

POST /validate
X-API-Key: <key>
Content-Type: application/json

{
  "entity_class": "infrastructure",
  "data": {
    "capacity_kw": 500,
    "cooling_type": "rdhx"
  }
}

POST /edr/validate        # EDR domain validation
POST /edr/validate/batch  # Batch EDR validation

Rule CRUD

GET  /rules              # List all rules
GET  /rules/{rule_id}    # Get single rule
PATCH /rules/{rule_id}   # Update rule fields
DELETE /rules/{rule_id}  # Delete rule

GET  /rules/{rule_id}/history  # Audit trail

GET  /rules/files              # List rule files on disk
GET  /rules/files/{file_path}  # Get file contents
GET  /rules/files/{file_path}/rules  # Rules in a specific file

deltaPrism Rule Execution

POST /delta-prism/execute-rules      # CPU rule execution
POST /delta-prism/execute-rules-gpu  # GPU-accelerated rule execution

Register a Subscription

POST /cdc/subscribe
X-API-Key: <key>
Content-Type: application/json

{
  "event_type": "record.created",
  "source": "crm",
  "pipeline_id": 42
}

Fire an Event

POST /cdc/event
Content-Type: application/json

{
  "event_type": "record.created",
  "source": "crm",
  "payload": { "id": "abc123", "name": "Acme Corp" }
}

GET /cdc/subscriptions  # List all active subscriptions

App Registration Sequence

• Create org

  POST /orgs  { "slug": "my-app", "name": "My App", "plan_tier": "enterprise" }

• Create teams and users

  POST /orgs/my-app/teams  { "slug": "admin-team", "name": "Admins" }
  POST /orgs/my-app/teams/admin-team/users  { "email": "admin@example.com", "role": "admin" }

• Issue an API key for the app

  POST /orgs/my-app/api-keys  { "label": "app-runtime", "scopes": ["read","execute"] }

  Store the returned raw key. It will not be shown again.

• Define pipelines

  Create pipelines with POST /pipelines. Each pipeline defines a graph_json of typed nodes and edges. Fetch node type schemas from GET /node-types to understand required fields.

• Register in app catalog

  Add an entry to admin/seed_nx_s18_app_catalog.py in the Wormwood repo with slug, display_name, domain, and actions. Re-seed to make it appear in GET /orgs/apps/catalog.

• Build the SPA (optional)

  Create a self-contained HTML SPA that calls the Nexus API using the app's key. Use the pipeline canvas endpoint (GET /pipelines/{id}/canvas/{scale}) for graph rendering. Use Chameleon node schema endpoints for form rendering. Wire SSE for live status.

App Catalog API

# All apps
GET /orgs/apps/catalog

# Single app by slug
GET /orgs/apps/catalog?slug=my-app

Response shape:

{
  "slug": "my-app",
  "display_name": "My App",
  "domain": "Finance",
  "status": "operational",
  "actions": ["Intake", "Review", "Approve"],
  "components": [
    { "name": "Wormwood", "version": "1.4.4" }
  ]
}

Entity Classes (Schema Registry)

Define custom entity schemas for your org. These drive validation and form rendering.

POST /orgs/{org_slug}/entity-classes
{ "slug": "invoice", "schema": { ... JSON Schema ... } }

GET  /orgs/{org_slug}/entity-classes
GET  /orgs/{org_slug}/entity-classes/{class_slug}
DELETE /orgs/{org_slug}/entity-classes/{class_slug}

ARC Schema (Global Read-Only)

GET /arc/classes             # List global ARC entity classes
GET /arc/schema/{class_slug} # Get ARC class schema