Skip to content
OBML v1.0
OrionBelt v2.34.0

API Overview

OrionBelt exposes a REST API for task-specific model-and-query batches, session-based model management, validation, query compilation, and query execution.

REST API

Base URL

http://127.0.0.1:8000

Content Type

All endpoints accept and return JSON:

Content-Type: application/json

Routers

All API routes are prefixed with /v1/ except /health and /robots.txt.

Prefix Tag Description
/v1/oneshot/batch oneshot Submit inline OBML or reference a loaded model, then compile or execute multiple independent queries in one request
/v1/sessions sessions Session-scoped model management, validation, query compilation, and execution
/v1/sessions/.../models/.../ model-discovery Schema, dimensions, measures, metrics, explain, find, join-graph
/v1/schema, /v1/dimensions, ... model-discovery Top-level shortcuts (auto-resolve single session/model)
/v1/convert convert OSI ↔ OBML format conversion with validation
/v1/dialects dialects Available SQL dialect info
/v1/settings settings Public configuration: version, single-model mode, TTL, model settings, timezone & dialect resolution
/health health Health check (no prefix)

One-shot Agent Workflow

An agent can author a model for a set of questions and submit the model and queries together to POST /v1/oneshot/batch. Provide model_yaml and a queries list; OBSL creates a session when needed, validates the model, and returns an individual result for each query. Compilation is the default; set execute: true to run queries when database execution is configured.

Freshly loaded models are removed after the batch by default. Set persist_model: true to retain a model in the session and use the returned session_id and model_id in later batches. Existing models that are referenced or reused are retained. The session itself remains until closed or expired.

See Agent Workflows for a complete example and One-shot Batch for the request and response contract.

Session-Based Workflow

For iterative model management and discovery, use sessions explicitly:

  1. Create a session — POST /v1/sessions returns a session_id
  2. Load models — POST /v1/sessions/{id}/models with OBML YAML
  3. Compile — POST /v1/sessions/{id}/query/sql to compile OBML to SQL
  4. Execute — POST /v1/sessions/{id}/query/execute to compile and execute against the database (requires FLIGHT_ENABLED=true)
  5. Close — DELETE /v1/sessions/{id} when done (or let TTL expire)

Sessions expire after 30 minutes of inactivity (configurable via SESSION_TTL_SECONDS) or after an absolute maximum lifetime of 24 hours (SESSION_MAX_AGE_SECONDS). The server enforces a global concurrent session cap (MAX_SESSIONS, default 500) and a per-session model cap (MAX_MODELS_PER_SESSION, default 10). Session creation is rate-limited per IP (SESSION_RATE_LIMIT, default 10/min). When limits are exceeded, the API returns 429 Too Many Requests with a Retry-After header. Expired sessions return 410 Gone (not 404) so clients can distinguish expiry from unknown IDs.

Admin-Curated Mode

When the MODEL_FILES environment variable is set, the server runs in admin-curated mode — each preloaded model lives in its own named protected session whose id is the OBML name: field (falling back to the filename stem):

  1. Discover — GET /v1/models lists every preloaded model and its addressing name
  2. List the model — GET /v1/sessions/<model_name>/models to get the model_id
  3. Compile — POST /v1/sessions/<model_name>/query/sql to compile OBML to SQL
  4. Execute — POST /v1/sessions/<model_name>/query/execute to compile and execute (requires FLIGHT_ENABLED=true)

BI tools through Flight SQL or pgwire select the same model via the database header / URL parameter. Model upload (POST /v1/sessions/{id}/models) and removal (DELETE /v1/sessions/{id}/models/{mid}) return 403 Forbidden while admin-curated mode is on. All other endpoints work normally.

Error Responses

All errors follow a consistent format:

{
  "detail": "Session 'abc123' not found"
}

Status Codes

Code Meaning When
200 OK Successful GET or compilation
201 Created Session or model created (POST)
204 No Content Session or model deleted
400 Bad Request Invalid YAML, unknown dialect, bad operator
403 Forbidden Model upload/removal in single-model mode
404 Not Found Session expired/missing, model not found
422 Unprocessable Entity Model validation failure, resolution error
502 Bad Gateway Database execution failed (query/execute)
503 Service Unavailable Query execution not available (FLIGHT_ENABLED not set)

Middleware

Request Timing

The RequestTimingMiddleware adds X-Request-Duration-Ms headers for performance monitoring.

Interactive Documentation

When the server is running, interactive API docs are available at:

  • Swagger UI: http://127.0.0.1:8000/docs
  • ReDoc: http://127.0.0.1:8000/redoc

Both are auto-generated from the FastAPI route definitions and Pydantic schemas.