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¶

Authentication expectations¶

Gateway API — /v1¶

Authentication¶

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

{"email":"user@example.com","password":"<user-password>"}

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

Membership¶

Roles are admin and user (member). Account and token lifecycle details are in Single-organization operation.

Chargers and telemetry¶

Telemetry 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/telemetry/charger-123/data?type=controllerCpuUsage&limit=200
Authorization: Bearer <token>

Generic catalogue and collection¶

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. /sources and the provider-specific catalogue endpoints have been removed.

The /system/live session API starts explicitly bounded in-memory previews. Acquiring a lease requires an administrator; members can inspect an existing session. Preview does not enable persistent collection. Accepted detector topics use only telemetry/<entity>/<reading>; upstream topics can use arbitrary concrete MQTT paths and JSON Pointer payload bindings.

Monitoring and model discovery¶

The chart cursor is the complete tuple after_created, after_timestamp, after_service_id, and after_sequence_number; if one is supplied, all four are required.

A monitor start body contains:

• required container_name and mqtt_topics
• 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 for sensor alignment

Omitting monitoring selects the default static baseline. The former top-level strategy, model_type, model_params, static_baseline_config, and adaptive_stream_config fields remain accepted at API ingress and are converted to monitoring. Mixing the two formats, conflicting model fields, and malformed configuration return HTTP 422. The gateway forwards only the canonical format to TACTIC.

TACTIC converts the configuration into its equivalent graph, binds each topic to its selected numeric catalogue reading and submits a pipeline activation, even while the visual workbench is disabled. The HTTP 202 response carries service_id, activation_id, container_name, status (the activation phase) and mqtt_topics. Poll /monitors/pipeline-activations/{activation_id} until the service exists. Topics without a selected numeric reading return HTTP 422.

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

Visual monitoring interfaces use the same authenticated /v1/monitors prefix:

Use publication and activation for graph starts. The legacy /start endpoint remains compatible with existing callers; 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 service and expose retained input metadata, terminal errors and compiler feature lineage. POST /pipelines/{id}/validate accepts {definition, selected_node_id?}; GET /{service_id}/pipeline accepts the same optional selected_node_id query 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 anomalies¶

Gateway health¶

TACTIC API — /api/v1¶

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

Data adapter¶

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 current active-ID Gateway route is singular: /chargers/active/id.
• 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