ODEI Runtime + API Documentation

Inspect the Desktop Runtime and API Contract Behind ODEI

api.odei.ai now documents the real ODEI stack: the authenticated Builder install lane in app.odei.ai, the macOS and Windows desktop builds, the Neo4j-backed local runtime, public runtime routes, and the governed Digital World Model API v2. Use this page to validate what ships locally, what stays public, and where signed clients enter the query plane.

Base URL https://api.odei.ai Single production origin for docs, release artifacts, and runtime contracts.

Desktop Lane macOS + Windows Public release lane currently ships the local-first desktop runtime on both platforms.

Local Substrate Neo4j + SQLite + MCP World Model, dialogue continuity, and context control stay on the operator machine.

Open Builder Desktop release manifest OpenAPI JSON

For operators

Install the same ODEI desktop runtime shown in Builder.

The Builder tab in app.odei.ai now acts as the authenticated deployment surface. It shows the live desktop product, points to the versioned downloads, and keeps the install contract honest: World Model, SQLite continuity, MCP services, and the Neo4j-backed graph runtime stay local.

1. Open Builder in app.odei.ai 2. Install Neo4j Community Edition 3. Download the macOS or Windows desktop build

Open Builder Desktop release manifest Neo4j Community Edition

Exact desktop artifacts

macOS DMG Windows x64 setup Windows arm64 setup macOS update feed Downloads index

For agents and integrators

Verify release artifacts, public routes, and the signed v2 query plane from one surface.

Local AI agents can use this same surface to help operators finish installation. External clients should still pin the public OpenAPI, the v2 schema, and the desktop release manifest before they rely on any governed or installer-dependent flow.

Release manifest V2 routes Contract artifacts

Local-first truth

World Model state, SQLite continuity, MCP services, and provider lanes remain on the operator machine.

Release truth

Versioned desktop artifacts and the macOS updater feed are published from the same production origin.

Lane separation

Desktop install, public read routes, consent-gated writes, and authenticated v2 queries are documented as distinct trust lanes.

Total Routes -- Cataloged in this reference

Public Runtime -- No auth required

Authenticated V2 -- Bearer or X-Api-Key

Contract Artifacts -- Specs, release feeds, and payment metadata

Current production posture

Model the system by boundary, not by marketing surface.

Builder lane Authenticated install surface inside app.odei.ai

Desktop runtime Local-first graph, continuity, and operator workspace

Public runtime Health, live World Model projection, token telemetry

Digital World Model API v2 Signed client with quota awareness

Quickstart in 3 Checks

Validate runtime health, inspect the desktop release lane, then read the live World Model and schema surfaces that already exist. This gives you a clean baseline before you wire governed v2 access or ship any installer-dependent workflow.

Bootstrap in under 60 seconds

Verify runtime and machine-readable contracts

Confirm the public API is alive and that the canonical public contract artifact is fetchable.

curl -fsS https://api.odei.ai/health
curl -fsS https://api.odei.ai/openapi.json

Inspect the desktop release lane

Validate the published build manifest and updater feed before you rely on the desktop runtime.

curl -fsS https://api.odei.ai/downloads/release.json
curl -fsS https://api.odei.ai/downloads/latest-mac.yml

Read the live World Model and schema

Use the zero-auth read lane first, then bind signed clients to the v2 query plane.

curl -fsS https://api.odei.ai/api/worldmodel/live
curl -fsS https://api.odei.ai/api/v2/schema

Boundary rule: desktop installs are local-first and require Neo4j Community Edition on the same machine. Signed v2 world-model and guardrail routes (/api/v2/world-model/*, /api/v2/guardrail/check) still require Authorization: Bearer ... or X-Api-Key. Only /api/v2/health and /api/v2/schema are public. Treat local desktop runtime and signed v2 API clients as separate system boundaries.

Desktop Runtime Contract

Builder inside app.odei.ai is now the authenticated deployment surface for ODEI.app. The browser shows the real product video, versioned macOS and Windows downloads, and the install contract. The terminal, graph, SQLite continuity, and MCP runtime remain local on the operator machine.

Install lane, not a browser simulation

Builder install lane

The authenticated Builder surface is the public front door to the local-first runtime, not a replacement for it.

Builder surface:
- live desktop app video
- versioned macOS / Windows downloads
- exact install contract
- AI-assisted setup fallback

Open Builder Release manifest

Local requirements

ODEI does not fake the graph layer in the browser. The build expects the real local substrate to exist on the same machine.

Required on the same machine:
- Neo4j Community Edition
- one supported provider CLI
- Claude Code, Codex, or Gemini CLI
- local machine you control

Neo4j Community Edition macOS Neo4j guide Windows Neo4j guide

Promotion rule

An install only becomes meaningful when the local runtime actually comes online with the operator's stack behind it.

Install becomes live when:
- ODEI launches locally
- graph + SQLite + MCP come online
- the chosen provider lane is attached
- the runtime verifies successfully

Current public scope

The public release lane is intentionally narrow and explicit.

Public release lane:
- macOS build
- Windows x64 build
- Windows arm64 build
- versioned updater feed
- Linux not in the current public lane

What Ships in the Build

The desktop runtime is already concrete. These are the technical layers the current Builder install lane delivers, not a roadmap wish list.

Real local-first runtime layers

World Model

The build includes the real World Model surface with sectors, filters, search, and ODEI styling running against local graph state.

World Model:
- sector structure
- filters + search
- local graph-backed rendering

Agent workspace

The local workspace is designed around a real terminal and provider lanes instead of a hosted browser chat.

Provider lanes:
- Claude Code
- Codex
- Gemini CLI

MCP stack

Bundled MCP services manage graph context, memory retrieval, dialogue history, and runtime coordination from inside the installed environment.

MCP services:
- graph context
- memory retrieval
- dialogue history
- runtime coordination

SQLite continuity

Conversation state is persisted locally in SQLite so the operator keeps a recoverable trail instead of resetting every session.

SQLite continuity:
- local conversation state
- recoverable history trail
- no zero-state restart

Neo4j graph runtime

Neo4j Community Edition hosts the local graph ODEI uses for World Model state, memory structure, and persistent context topology.

Neo4j role:
- World Model state
- memory structure
- persistent context topology

Updates

The release lane is versioned and publishes updater artifacts from the same production origin as the docs.

Release lane:
- versioned desktop artifacts
- release manifest
- macOS updater feed
- update prompts in packaged installs

Local-First Boundary

ODEI is not a hosted browser terminal pretending to be local. The graph, continuity, and operator workspace stay on the user's machine, while the public API remains a separate contract surface for discovery, schema, and governed query access.

Two honest system boundaries

What stays local

- World Model state
- SQLite dialogue continuity
- MCP services
- provider lanes
- local graph runtime

What stays public

- docs + release artifacts
- health + world-model projection
- token telemetry
- v2 schema + signed query plane

AI-assisted setup

If installation needs help, the recommended fallback is the same local-first posture: ask your local AI agent to finish the machine setup instead of routing the work back through a hosted browser flow.

Ask your local AI agent to:
- finish Neo4j setup
- validate terminal/runtime dependencies
- complete the local environment
- verify the app launch path

API Surface Map

ODEI exposes multiple lanes with different trust, auth, and operational constraints. Build your SDK and monitoring around these lanes so the integration stays clean as the runtime expands.

Lane-aware by design

Loading lane map...

Auth and Governance Matrix

Every lane has a different operational contract. Treat auth, rate limits, and governance posture as part of the domain model, not as an afterthought in the UI.

Lane	Auth model	Primary use	Guardrails
Public runtime	None	Health, projection, context, token telemetry	Read routes, server-side sanitization
Builder + consented writes	None + explicit consent payload	Builder bootstrap metadata and consent-gated write surfaces	20 writes/min/IP + payload validation
Digital World Model API v2	Bearer JWT or X-Api-Key	Structured graph query and constitutional checks	Auth middleware + daily quota counters
x402 contract metadata	Public JSON artifact	Payment capability discovery for clients	Declarative manifest (`/.well-known/x402.json`)

Trust, Failure, and Retry Contract

Production clients should treat anonymous reads and signed v2 requests as separate modes. Build around the real response envelopes below, not around optimistic assumptions.

Exact lane semantics

Public success

Anonymous health and schema reads are safe entry points.

Humans and agents can start with public runtime reads. These routes are the correct place to confirm liveness, schema shape, and contract reachability before any signed call.

curl -fsS https://api.odei.ai/health
curl -fsS https://api.odei.ai/api/v2/health
curl -fsS https://api.odei.ai/api/v2/schema

Governed failure

Signed v2 routes fail closed with a deterministic 401 envelope.

Unauthenticated calls to governed world-model and guardrail routes return the same explicit unauthorized contract. Handle this as a normal state transition, not as an ambiguous server fault.

{
  "ok": false,
  "error": "Missing authentication credential",
  "code": "UNAUTHORIZED"
}

API client bootstrap

Recommended order for a signed API client.

Read /health and /openapi.json.
Fetch /api/v2/schema to bind the graph model.
Store auth material outside the anonymous client.
Use signed requests for /api/v2/world-model/* and /api/v2/guardrail/check.
Treat /.well-known/x402.json as a published artifact, not as an auth grant.

Endpoint Reference

Search by route, method, lane, auth model, or tag. The catalog below is grouped by trust lane so the reference scales as ODEI adds more public, governed, and machine-contract surfaces.

Lane-grouped catalog

Loading endpoint catalog...

Reference Flows

Keep these flows in CI smoke tests so contract regressions are detected before deployment.

Production smoke patterns

1) Runtime Smoke

Verify server liveness and public contract endpoint.

curl -fsS https://api.odei.ai/health
curl -fsS https://api.odei.ai/openapi.json

2) Desktop Release Verification

Pin the current desktop version and updater feed before you automate installer-dependent flows.

curl -fsS https://api.odei.ai/downloads/release.json
curl -fsS https://api.odei.ai/downloads/latest-mac.yml

3) Live World Model Read

Confirm the zero-auth graph projection before you move into signed query clients.

curl -fsS https://api.odei.ai/api/worldmodel/live
curl -fsS https://api.odei.ai/api/worldmodel

4) V2 Query/Auth

Execute authenticated graph query on v2 lane.

curl -X POST https://api.odei.ai/api/v2/world-model/query \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"search":"guardrail","limit":5}'

Operational Contracts and Policy Links

Production integrations should pin these documents in your build and test pipeline.

Pin these in CI

Builder Install Surface Authenticated Builder lane inside app.odei.ai with the live desktop preview and downloads

Open

Desktop Release Manifest Canonical version, platform artifacts, and public download aliases

Open

macOS Updater Feed Published updater manifest consumed by packaged macOS installs

Open

Neo4j Community Edition Required local graph prerequisite for the current desktop runtime contract

Open

Public OpenAPI Machine-readable public runtime contract

Open

Digital World Model API v2 OpenAPI Extended schema for authenticated v2 query lane

Open

x402 Metadata Published commercial capability manifest for the governed paid query plane

Open

Policy and Legal Terms, Privacy, SLA, and Legal disclosures

View