QELLVISQUICKSTART

Quickstart

A minimal guide to get started with QELLVIS. Prepare your structure, call the engine, interpret the output. Deterministic behavior in three simple steps.

STEP 1 — PREPARE YOUR STRUCTURE

QELLVIS requires two lists: nodes and dependencies. Each node represents a unit of value. Each dependency defines directional flow.

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

STEP 2 — CALL THE API

Use the public API to analyze or simulate your system. All operations use a single POST endpoint.

POST /api/qellvis
Authorization: Bearer YOUR_API_KEY

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

Modes:
• analyze — one‑time interpretation
• tick — single step
• ticks — multi‑step timeline

STEP 3 — INTERPRET THE OUTPUT

The engine returns structural behavior: flow, pressure, blockages, events, origin and trace.

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

OPTIONAL — CONNECT AN EXTERNAL API

Instead of sending structure manually, you can connect an external API. QELLVIS fetches your endpoint, extracts structure and creates a system.

POST /api/connect
Authorization: Bearer <USER_ACCESS_TOKEN>

{
  "name": "My System",
  "url": "https://example.com/api",
  "auth": { "token": "optional" }
}

Your API must return nodes and dependencies and must allow CORS (see CORS & Systems page).

BEST PRACTICES

• keep structures minimal
• ensure node ids are unique
• avoid unnecessary metadata
• use ticks only when temporal evolution is required
• validate your external API with a simple POST test