Backend API guide¶

This is the contract-oriented reference for the currently wired backend surfaces.

When to use this page¶

Use this page when integrating a client, validating endpoint contracts, or triaging Gateway-to-TACTIC errors.

Base URLs¶

Deployed installations serve the gateway under /api on the dashboard host and start it with --root-path /api. Its schema at /api/openapi.json therefore names /api under servers, and the interactive schema opens at /api/docs.

The gateway's OpenAPI document is written for clients that read it instead of this page, AI agents included. Every operation is named after its handler, has a description, and protected operations declare the bearerAuth scheme rather than an Authorization parameter. The document's introduction maps the web app's words (sources, readings, monitors, alarms) to the API's. Contract tests in backend/tests/contracts/test_gateway_openapi.py keep it that way.

Authentication expectations¶

Gateway API — /v1¶

Authentication¶

POST /v1/auth/login
Content-Type: application/json

{"email":"[email protected]","password":"<user-password>"}

{
  "access_token": "<bearer-token>",
  "token_type": "bearer",
  "member_id": 7
}

Membership¶

Every active member can read everything outside the Dojo. A role grants the permissions: manage_sources (catalogue, collection and live preview), manage_monitors (monitors and pipelines), manage_alarms (creating and deleting alarms), use_dojo (the Dojo, reads included) and manage_members (members and roles). GET /me returns the member's role and the permissions it grants. Two roles are built in: admin (Administrator) always holds every permission and cannot be changed, and user (Member) is what an invitation gives unless it names another role. Neither can be deleted. A change that would leave no active member able to manage members is refused with 409. Account and token lifecycle details are in Single-organization operation.

Devices and measurements¶

Devices and readings are named by their catalogue ids, devices[].id and readings[].id of GET /v1/catalogue. The installation resolves where their values are stored.

Measurement cursors:

• Use after_timestamp for historical event-time pagination.
• Use after_created and after_event_timestamp together for live ingestion-order pagination.
• Do not mix historical and live cursor forms.

GET /v1/readings/stream:cpu-usage/measurements?limit=200
Authorization: Bearer <token>

Catalogue, recording and live views¶

The catalogue document holds brokers, devices, readings and groups; devices and readings name their broker as broker_id. A broker's protocol is mqtt or http. On an HTTP broker a reading's topic is its request path, and the reading may carry a timestamp_pointer; the field is absent from readings that have none. Changes need manage_sources, which TACTIC checks.

Catalogue documents use only aberration-system schema version 1. New inputs remain Off regardless of policy metadata in an import. The UI reviews structural replacement before saving; existing selections survive by stable reading ID. Files exported before the rename, with connections, streams and connection_id, still import.

/recording/health decides the recording diagnosis on the server. The checks run in a fixed order (catalogue saved, collector report younger than 15 seconds, local MQTT connected, revisions applied, broker routes, broker connections, database, traffic) and the first that fails is returned as diagnosis.code with a title, tone and explanation. The web app shows that verdict unchanged; it only adds "Status not refreshing" when the endpoint itself stops answering.

Live views are explicitly bounded in-memory previews. Opening one requires manage_sources; members can read the measurements of an open view. A live view does not record anything. Accepted detector topics use only telemetry/<entity>/<reading>; upstream topics can use arbitrary concrete MQTT paths and JSON Pointer payload bindings.

Monitors, pipelines and detectors¶

A monitor is named by its monitor_id everywhere; container names, container ids and Docker states stay inside the installation. Members read everything here; changes need manage_monitors.

Evidence rows name their monitor_id and the reading_ids they covered; input_timestamps is keyed by reading id. The chart cursor is the complete tuple after_created, after_timestamp, after_monitor_id, and after_sequence_number; if one is supplied, all four are required.

Every listed monitor, here and in /monitors/overview, carries reading_ids: the catalogue readings it watches. Use it to answer "which monitors watch this reading"; a reading removed from the catalogue drops out. A monitor's operational_status names its inputs by reading id as well. How a reading is recorded (its topic and ingress key) stays inside the backend. active is true while the monitor should run and false once it is stopped.

A monitor start body contains:

• required display_name and reading_ids: up to 100 distinct numeric readings that are recorded, all of one device or all of one broker without a device
• monitoring: the strategy configuration, including strategy (static_baseline or adaptive_stream), model_type, model_params, and the strategy's training, calibration, and alarm settings
• optional performance_config: sensor_freshness_seconds, observation_max_age_seconds, observation_future_tolerance_seconds and alignment_max_skew_seconds

Omitting monitoring selects the default static baseline. Other fields, including the former top-level mqtt_topics, strategy, model_type and model_params, and malformed configuration return HTTP 422.

TACTIC converts the configuration into its equivalent graph, binds one input per reading and submits a pipeline activation, even while the visual workbench is disabled. The graph's inputs carry the readings' catalogue labels. The HTTP 202 response carries monitor_id, activation_id, phase and reading_ids. Poll /pipeline-activations/{activation_id} until its phase is succeeded, failed or cancelled. A reading that is unknown, not numeric, not recorded or of another device returns HTTP 422.

A run view (/monitors/{monitor_id}/pipeline) names its bound inputs by slot_id, reading_id and unit. Its binding_metadata keeps the catalogue_revision and collection_revision the run was bound against and, per reading, the catalogue label, unit, device_id, device_label, broker_id, broker_label and collection_policy at that time.

Use /detectors as the source for valid model names and parameter schemas.

bindings map each input slot of a design to a catalogue reading id. Repeating an apply or activation with the same idempotency_key returns the first activation instead of starting another; replace_monitor_id swaps out a running monitor. Direct public graph launches are rejected so they cannot bypass preflight, durable input reservations or run history. Draft/layout conflicts return HTTP 409. Publishing does not activate a revision. Run views survive deletion of the live monitor and expose retained input metadata, terminal errors and compiler feature lineage. /monitors/{monitor_id}/pipeline accepts an optional selected_node_id for member inspection even when authoring is disabled. Each compiler report is bounded to 512 KiB, omitting provenance and then whole unselected node tables with a metadata_budget notice. Complete ordered names for the selected node and its immediate parents remain available; inspect features_complete and provenance_complete before interpreting missing metadata. Invalid oversized definition echoes use definition: null and definition_omitted: true; bounded errors expose issues_truncated. Internal MQTT overrides and runtime image pins are rejected by public monitor creation. See pipeline architecture and rollout.

Favourites and alarms¶

A favourite's kind is device (a catalogue device id), reading (a catalogue reading id) or monitor (a monitor_id). Ids are not checked against the catalogue, so a favourite stays until the member removes it. A member keeps at most 256; adding another answers 409.

An alarm names its catalogue device_id and reading_ids with their names in device_label and reading_labels. A reading without a device has a null device_id, and device_label names its broker. Readings the catalogue no longer has are left out. multivariate marks an alarm a monitor raised over several readings together. A manual alarm names readings of one device, or of one broker without a device; several make it multivariate.

POST /alarms/query is a read, so members may call it although other POST routes under /alarms need manage_alarms. An alarm is in the reading_ids scope when one of its readings is. A multivariate alarm recorded without its readings is only in scope when every reading of its device is. summary and readings cover every match rather than the returned page; readings ignores the narrowing filters so it can feed a reading picker. Pages are newest first; pass next as before.

Dojo¶

Datasets and runs for comparing detection approaches offline, apart from live monitoring. A dataset is a frozen copy: retention and catalogue edits never change it. A run replays one design over one dataset. Every route needs use_dojo, reads included, because datasets are copies made for experiments.

A wide CSV has one timestamp column (the first unless timestamp_column names another) and one series per remaining column; a long CSV has one value per row in series, timestamp and value columns. Timestamps are ISO 8601 or Unix epoch seconds or milliseconds, UTC without a zone. The delimiter is detected from the header; with ; or tab a decimal comma is accepted. A dataset holds at most 64 series and 5,000,000 values, and two values for the same series and instant are rejected.

A run is compiled and bound when it is created, so a design error is refused at once. The Dojo worker, a service on the RADAR image, then replays the bound series in time order through the same alignment and detector code as a live monitor. The clock is the data's own time, so alignment.freshness_seconds and alignment.max_skew_seconds mean what the live monitor settings mean. A static baseline's fitting is awaited instead of discarding observations, so the same run gives the same results again. Each worker replica executes one run at a time; at most 20 runs wait or run at once. A run's stats count observations that produced no result, by reason.

A label marks a known problem as the interval from start_at to end_at. Labels of one dataset may touch but not overlap and must overlap the dataset's time span; a dataset holds at most 500. Metrics treat each label as one event and are computed when read, from the stored results and the current labels, so editing a label re-scores every finished run without a replay. A label is detected when the run alarmed inside it, ends included, with delay_seconds from its start to the first alarm; missed when the run scored it without alarming; and unscored when the run had no scores during it, for example while the detector was still learning. detection_rate divides detected labels by scored ones. Each alarm onset outside every label is one false alarm, so an alarm held over many results counts once, and one that starts inside a label and outlasts it does not count. false_alarms_per_day divides them by evaluated_seconds, the scored time outside the labels. Only runs with status succeeded have metrics.

A run created with compare_calibration also tries the other calibration methods on its own detector scores: the fixed split and the 15 methods that adapt, without the run's own. Each gets the calibration window and then every scored observation, as the run's own calibration step does, and nothing a method decides reaches the run. All aim at one alarm rate, alpha, and alarm after consecutive scores in a row above their boundary. A run whose step adapts gives its own alpha and the consecutive of its detection rule; a fixed split gives the share its quantile leaves above the threshold, at least one in n + 1 for a calibration window of n, and consecutive 1. The other methods run with their default settings. A design that alarms on a conformal martingale has no boundary on scores and is refused with 422. GET /dojo/runs/{run_id}/calibration lists the run's own step first (own), then the others, each with the event metrics above counted from the first result the methods judged, and alarm_share, the share of judged results it would have alarmed on. A method that raised an error on the scores stops there and says why in failed; the run itself carries on. Its counts are of what it found until then, and alarm_share, detection_rate and false_alarms_per_day are null, because they would be over results it never judged.

Promoting a run copies its compiled design into the pipeline library as a new template, the same as POST /pipelines, so pipeline authoring must be enabled and the member needs manage_monitors. The answer names the new pipeline_id and lists each input slot with the series it was bound to. For a series copied from recorded history, reading_id is the catalogue reading it came from, the live input to bind when the template starts a monitor; an uploaded series has none. The template has no published revision yet.

Import and metrics bounds¶

CSV imports accept up to 65 columns per record (a timestamp and 64 series), 64 Ki characters per logical record, and 256 characters per series name. These limits also apply to quoted multiline records and unused columns in long CSVs. Ordinary wide and long CSV uploads retain their existing overall upload limits.

Run, run-comparison, and calibration-comparison metrics cache their bounded aggregates until label intervals change. An uncached calculation uses a shared database slot and returns a retryable conflict when another calculation holds it. Calculations have a 30-second request deadline and a 25-second database statement deadline. These protections use built-in defaults and need no new environment variables.

Gateway health¶

TACTIC API — /api/v1¶

All business routes require X-Off-Key-Service-Key; collection, membership and role routes additionally validate the end-user bearer token and its permissions. TACTIC is private. Health and readiness remain available without this service credential.

The gateway is the only caller. Its routes above forward to these, under the names the installation uses internally: a catalogue is the system, recording is collection, a broker is a connection, a live view is a lease and a monitor is a service.

Members, sessions and roles¶

Catalogue, recording and live views¶

Pipelines and monitor runs¶

Data adapter¶

Dojo¶

RADAR orchestration¶

Model catalogue¶

The catalogue is served from code (off_key_core.models). Adding a model means shipping its implementation and catalogue entry.

Middleware health¶

Error model¶

FastAPI validation errors and Gateway-propagated TACTIC errors use a detail field; exact payload shape varies by layer.

Compatibility notes¶

• The Gateway API family remains /favorites. The dashboard's Favorites filter uses /?state=favorites; the old /favourites frontend route redirects there.
• Removed sync and preprocessor-discovery routes must not be used by new clients.

Related pages¶

• Architecture
• Data model
• Testing and debugging
• Web app