QELLVISAPI

QELLVIS API

The official programmatic interface to the QELLVIS System Behavior Engine. Fully deterministic. Structure‑driven. Minimal JSON in, structural behavior out.

ENDPOINT

All operations use a single POST endpoint:

POST /api/qellvis

AUTHENTICATION

The API requires a valid API key using Bearer authentication.

Authorization: Bearer YOUR_API_KEY

Keys are hashed and validated against the api_keys table. Inactive or unknown keys are rejected.

PAYLOAD STRUCTURE

The API accepts two formats: direct structure or nested structure.

Direct:

{
  "nodes": [...],
  "dependencies": [...],
  "mode": "analyze | tick | ticks",
  "ticks": 5
}

Nested:

{
  "payload": {
    "nodes": [...],
    "dependencies": [...]
  }
}

Alternative keys supported: system, record, data, graph.

MODES

The engine supports three deterministic execution modes.

• analyze — one‑time structural interpretation
• tick — single execution step
• ticks — multi‑step execution with snapshots

EXAMPLES

Analyze:

{
  "mode": "analyze",
  "payload": {
    "nodes": [
      { "id": "A", "load": 10 },
      { "id": "B", "load": 0 }
    ],
    "dependencies": [
      { "from": "A", "to": "B" }
    ]
  }
}

Tick:

{
  "mode": "tick",
  "nodes": [...],
  "dependencies": [...]
}

Ticks:

{
  "mode": "ticks",
  "ticks": 3,
  "payload": { ... }
}

RESPONSES

Analyze:

{
  "mode": "analyze",
  "engine": {
    "nodes": [...],
    "dependencies": [...],
    "primaryBlockage": "...",
    "events": [...],
    "origin": {...},
    "trace": [...]
  }
}

Tick:

{
  "mode": "tick",
  "snapshot": { ... }
}

Ticks:

{
  "mode": "ticks",
  "ticks": 3,
  "snapshots": [...]
}

ERRORS

• 400 — Invalid mode
• 401 — Missing API key
• 403 — Invalid or inactive API key
• 500 — engine or payload error