{ "components": { "parameters": { "asOf": { "in": "query", "name": "as_of_ns", "required": false, "schema": { "format": "int64", "type": "integer" } }, "cursor": { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, "limit": { "in": "query", "name": "limit", "required": false, "schema": { "minimum": 1, "type": "integer" } } }, "schemas": { "AdminChangeCommitConflict": { "oneOf": [ { "$ref": "#/components/schemas/AdminChangeDriftConflict" }, { "$ref": "#/components/schemas/AdminChangeStateConflict" }, { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "not": { "properties": { "code": { "const": "conflict" } }, "required": [ "code" ], "type": "object" } } ] } ] }, "AdminChangeDriftConflict": { "additionalProperties": true, "properties": { "code": { "const": "conflict" }, "correlation_id": { "format": "uuid", "type": "string" }, "details": { "additionalProperties": false, "properties": { "current": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "resource_id": { "format": "uuid", "type": "string" }, "revision": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" } }, "required": [ "resource_id", "revision", "name", "path" ], "type": "object" }, "current_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" } }, "required": [ "current_tx", "current" ], "type": "object" }, "error": { "type": "string" } }, "required": [ "error", "code", "correlation_id", "details" ], "type": "object" }, "AdminChangeStateConflict": { "additionalProperties": true, "properties": { "code": { "const": "conflict" }, "correlation_id": { "format": "uuid", "type": "string" }, "details": { "additionalProperties": false, "properties": { "state": { "enum": [ "committed", "cancelled", "failed" ], "type": "string" } }, "required": [ "state" ], "type": "object" }, "error": { "type": "string" } }, "required": [ "error", "code", "correlation_id", "details" ], "type": "object" }, "Capability": { "enum": [ "read", "annotate", "enter", "approve", "amend", "model-edit", "registry-manage", "calc-author", "display-author", "display-publish", "episode-manage", "redact", "admin" ], "type": "string" }, "CursorPage": { "properties": { "items": { "items": {}, "type": "array" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items" ], "type": "object" }, "DisplayDocument": { "$schema": "http://json-schema.org/draft-07/schema#", "definitions": { "AnchorResolution": { "description": "The result of resolving an anchored window's provenance (honesty-render LAW: never a silently substituted default range — an unresolvable anchor is an EXPLICIT reason).", "oneOf": [ { "properties": { "end": { "type": "string" }, "start": { "type": "string" }, "state": { "enum": [ "resolved" ], "type": "string" } }, "required": [ "end", "start", "state" ], "type": "object" }, { "properties": { "reason": { "type": "string" }, "state": { "enum": [ "unresolved" ], "type": "string" } }, "required": [ "reason", "state" ], "type": "object" } ] }, "AttributeSelector": { "oneOf": [ { "properties": { "kind": { "enum": [ "template-relative" ], "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "name" ], "type": "object" }, { "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "attribute-id" ], "type": "string" } }, "required": [ "attribute_id", "kind" ], "type": "object" }, { "properties": { "kind": { "enum": [ "unresolved" ], "type": "string" }, "name": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "kind", "name", "reason" ], "type": "object" } ] }, "ContinuityClass": { "enum": [ "continuous", "stepped", "event" ], "type": "string" }, "DisplayTimeContext": { "properties": { "end": { "type": "string" }, "navigator": { "$ref": "#/components/schemas/DisplayDocument/definitions/NavigatorSettings" }, "start": { "type": "string" }, "timezone": { "$ref": "#/components/schemas/DisplayDocument/definitions/DisplayTimezone" } }, "required": [ "end", "navigator", "start", "timezone" ], "type": "object" }, "DisplayTimezone": { "oneOf": [ { "additionalProperties": false, "properties": { "mode": { "enum": [ "automatic" ], "type": "string" } }, "required": [ "mode" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "enum": [ "explicit" ], "type": "string" }, "timezone": { "type": "string" } }, "required": [ "mode", "timezone" ], "type": "object" } ] }, "DocKind": { "enum": [ "display", "playlist", "session" ], "type": "string" }, "Layer": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "visible": { "default": null, "description": "visible: bool OR a binding object — kept as raw JSON (Spec 05 binding is W-later)." } }, "required": [ "id", "name" ], "type": "object" }, "Layout": { "enum": [ "structured", "free" ], "type": "string" }, "Meta": { "properties": { "description": { "default": null, "type": [ "string", "null" ] }, "form_factors": { "default": [], "items": { "type": "string" }, "type": "array" }, "layout": { "$ref": "#/components/schemas/DisplayDocument/definitions/Layout" }, "name": { "type": "string" }, "template": { "default": null, "type": [ "string", "null" ] } }, "required": [ "layout", "name" ], "type": "object" }, "Multistate": { "properties": { "bands": { "items": true, "type": "array" } }, "required": [ "bands" ], "type": "object" }, "NavigatorSettings": { "properties": { "visible": { "type": "boolean" } }, "required": [ "visible" ], "type": "object" }, "PenGlyph": { "enum": [ "circle", "square", "triangle", "diamond" ], "type": "string" }, "ScaleGroup": { "properties": { "id": { "type": "string" }, "max": { "default": null, "format": "double", "type": [ "number", "null" ] }, "min": { "default": null, "format": "double", "type": [ "number", "null" ] }, "mode": { "$ref": "#/components/schemas/DisplayDocument/definitions/ScaleMode" }, "x": { "additionalProperties": true, "type": "object" } }, "required": [ "id", "mode" ], "type": "object" }, "ScaleMode": { "enum": [ "template-range", "autofit", "explicit" ], "type": "string" }, "TimeRangeExpression": { "properties": { "end": { "type": "string" }, "start": { "type": "string" } }, "required": [ "end", "start" ], "type": "object" }, "TrendBindingKind": { "enum": [ "trend" ], "type": "string" }, "TrendBindings": { "additionalProperties": true, "properties": { "kind": { "$ref": "#/components/schemas/DisplayDocument/definitions/TrendBindingKind" }, "traces": { "items": { "$ref": "#/components/schemas/DisplayDocument/definitions/TrendTraceBinding" }, "type": "array" } }, "required": [ "kind", "traces" ], "type": "object" }, "TrendPen": { "additionalProperties": true, "properties": { "glyph": { "$ref": "#/components/schemas/DisplayDocument/definitions/PenGlyph" }, "token": { "type": "string" } }, "required": [ "glyph", "token" ], "type": "object" }, "TrendTraceBinding": { "additionalProperties": true, "properties": { "attribute": { "$ref": "#/components/schemas/DisplayDocument/definitions/AttributeSelector" }, "continuity": { "$ref": "#/components/schemas/DisplayDocument/definitions/ContinuityClass" }, "label": { "type": "string" }, "limits": true, "pen": { "$ref": "#/components/schemas/DisplayDocument/definitions/TrendPen" }, "quantity_kind_id": { "format": "uuid", "type": [ "string", "null" ] }, "scale_group": { "type": "string" }, "unit_id": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "attribute", "continuity", "label", "pen", "scale_group" ], "type": "object" }, "Widget": { "properties": { "bindings": { "allOf": [ { "$ref": "#/components/schemas/DisplayDocument/definitions/WidgetBindings" } ], "default": {} }, "grid": { "default": null }, "id": { "type": "string" }, "layer": { "default": null, "type": [ "string", "null" ] }, "link": { "default": null }, "multistate": { "anyOf": [ { "$ref": "#/components/schemas/DisplayDocument/definitions/Multistate" }, { "type": "null" } ], "default": null }, "range": { "anyOf": [ { "$ref": "#/components/schemas/DisplayDocument/definitions/Window" }, { "type": "null" } ], "default": null, "description": "Spec 04 §2.4 window object, verbatim (no parallel range grammar)." }, "time_override": { "anyOf": [ { "$ref": "#/components/schemas/DisplayDocument/definitions/TimeRangeExpression" }, { "type": "null" } ] }, "type": { "$ref": "#/components/schemas/DisplayDocument/definitions/WidgetKind" }, "x": { "additionalProperties": true, "type": "object" } }, "required": [ "id", "type" ], "type": "object" }, "WidgetBindings": { "anyOf": [ { "$ref": "#/components/schemas/DisplayDocument/definitions/TrendBindings" }, {} ], "description": "Trend bindings are typed Rust truth. Other widget kinds retain their complete forward-compatible JSON binding bags." }, "WidgetKind": { "description": "The FULL Spec 09 catalogue — schema-complete day-one. v1 renderers cover a subset; unrendered kinds render an honest placeholder tile (W3), never a schema break.", "enum": [ "trend", "bullet", "sparkline", "value-tile", "table", "state-indicator", "episode-gantt", "xy", "dot-bubble", "bar", "box", "strip", "interval-summary", "heatmap", "treemap", "multiline-text", "picture", "line", "symbol" ], "type": "string" }, "Window": { "description": "Spec 04 §2.4 window object (absolute | relative | anchored). Kept structurally faithful; the resolver (server-side) resolves it. Field names follow Spec 04 §2.4 verbatim (no-second-window-grammar LAW).", "oneOf": [ { "properties": { "end": { "type": "string" }, "start": { "type": "string" }, "type": { "enum": [ "absolute" ], "type": "string" } }, "required": [ "end", "start", "type" ], "type": "object" }, { "properties": { "last": { "type": "string" }, "type": { "enum": [ "relative" ], "type": "string" } }, "required": [ "last", "type" ], "type": "object" }, { "description": "The authored anchor is NEVER erased/rewritten (honesty-render LAW): `resolved` carries the RESULT of resolving it (or an explicit unresolved reason) ALONGSIDE the original `anchor`, never in place of it. Populated by `crate::resolve::resolve_document_windows`; `None` before resolution runs (the as-authored, pre-resolve state — e.g. straight off `transcode::from_yaml`).", "properties": { "anchor": true, "resolved": { "anyOf": [ { "$ref": "#/components/schemas/DisplayDocument/definitions/AnchorResolution" }, { "type": "null" } ] }, "type": { "enum": [ "anchored" ], "type": "string" } }, "required": [ "anchor", "type" ], "type": "object" } ] } }, "description": "The frozen envelope (overview §1). Unknown-but-versioned fields survive in `x`.", "properties": { "kind": { "$ref": "#/components/schemas/DisplayDocument/definitions/DocKind" }, "layers": { "default": [], "items": { "$ref": "#/components/schemas/DisplayDocument/definitions/Layer" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/DisplayDocument/definitions/Meta" }, "ordinate_display": { "description": "schema semver \"MAJOR.MINOR\".", "type": "string" }, "priority_order": { "default": [], "items": { "type": "string" }, "type": "array" }, "scale_groups": { "default": [], "items": { "$ref": "#/components/schemas/DisplayDocument/definitions/ScaleGroup" }, "type": "array" }, "time": { "allOf": [ { "$ref": "#/components/schemas/DisplayDocument/definitions/DisplayTimeContext" } ], "default": { "end": "*", "navigator": { "visible": true }, "start": "*-10m", "timezone": { "mode": "automatic" } } }, "widgets": { "default": [], "items": { "$ref": "#/components/schemas/DisplayDocument/definitions/Widget" }, "type": "array" }, "x": { "additionalProperties": true, "description": "Reserved extension bag — round-trip-preserved, never interpreted.", "type": "object" } }, "required": [ "kind", "meta", "ordinate_display" ], "title": "Document", "type": "object" }, "ErrorEnvelope": { "additionalProperties": true, "properties": { "code": { "enum": [ "account-sealed", "admin-change-internal", "admin-change-invalid", "attachment-redacted", "attachment-too-large", "authentication-required", "authorization-snapshot-unavailable", "backfill-job-not-found", "conflict", "cursor-invalid", "dependency-cycle", "display-doc-too-large", "display-folder-invalid", "display-folder-not-found", "display-invalid", "display-time-ambiguous", "display-time-invalid", "display-time-nonexistent", "forbidden", "id-token-verification-failed", "idempotency-key-conflict", "idempotency-key-invalid", "internal-read-error", "internal-subscription-error", "invalid-credentials", "invalid-json", "invalid-range", "invalid-uuid", "limit-exceeded", "model-unavailable", "model-unconfigured", "name-taken", "no-calc-lineage", "no-incumbent-at", "not-a-splice", "not-found", "oidc-not-configured", "operation-id-invalid", "operations-internal", "operations-query-invalid", "overlap", "preview-hash-mismatch", "recompute-required", "render-attribute-limit-exceeded", "render-overloaded", "render-span-limit-exceeded", "route-not-in-capability-map", "series-not-renderable", "sessions-human-only", "sse-subscriber-cap", "stat-not-rollup", "superseded-splice", "target-type-not-registered", "token-exchange-failed", "too-many-active-tokens", "unclassified", "writer-class" ], "type": "string" }, "correlation_id": { "format": "uuid", "type": "string" }, "details": { "type": "object" }, "error": { "type": "string" } }, "required": [ "error", "code", "correlation_id" ], "type": "object" }, "Lineage": { "additionalProperties": false, "properties": { "rule_id": { "format": "uuid", "type": "string" }, "rule_version_range": { "items": { "format": "int64", "type": "integer" }, "maxItems": 2, "minItems": 2, "type": "array" }, "windows": { "items": { "additionalProperties": false, "properties": { "end_ns": { "format": "int64", "type": "integer" }, "evaluated_at_ns": { "format": "int64", "type": "integer" }, "rule_version": { "format": "int64", "type": "integer" }, "start_ns": { "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns", "rule_version", "evaluated_at_ns" ], "type": "object" }, "type": "array" } }, "required": [ "rule_id", "rule_version_range", "windows" ], "type": "object" }, "LossyRange": { "additionalProperties": false, "properties": { "end_ns": { "format": "int64", "type": "integer" }, "start_ns": { "format": "int64", "type": "integer" }, "tag": { "type": "string" } }, "required": [ "start_ns", "end_ns", "tag" ], "type": "object" }, "ModelTreeNode": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "attributes": { "items": { "additionalProperties": false, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "retired": { "type": "boolean" } }, "required": [ "attribute_id", "name", "retired" ], "type": "object" }, "type": "array" }, "children": { "items": { "$ref": "#/components/schemas/ModelTreeNode" }, "type": "array" }, "effective_timezone": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" }, "retired": { "type": "boolean" }, "template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone_source_asset": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } }, "required": [ "asset_id", "name", "path", "template_id", "retired", "timezone", "effective_timezone", "timezone_source_asset", "attributes", "children" ], "type": "object" }, "PrincipalString": { "description": "Grant-subject grammar: system, user UUID, service UUID, or an IdP group name.", "pattern": "^(system|(user|svc):[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|group:.+)$", "type": "string" }, "Provenance": { "additionalProperties": false, "properties": { "chunks_pruned": { "minimum": 0, "type": "integer" }, "clock_suspect": { "type": "boolean" }, "compat_mode": { "enum": [ "none", "pi" ], "type": "string" }, "computed": { "const": "external", "type": "string" }, "contains_unknown_arrival": { "type": "boolean" }, "lineage": { "$ref": "#/components/schemas/Lineage" }, "lossy_ranges": { "items": { "$ref": "#/components/schemas/LossyRange" }, "type": "array" }, "model_as_of_ns": { "format": "int64", "type": "integer" }, "percent_good": { "type": "number" }, "percent_time_filtered": { "type": "number" }, "provisional_windows": { "items": { "$ref": "#/components/schemas/RangeNs" }, "type": "array" }, "quarantined_ranges": { "items": { "$ref": "#/components/schemas/RangeNs" }, "type": "array" }, "tiers_touched": { "items": { "enum": [ "hot", "warm", "cold" ], "type": "string" }, "type": "array" }, "window_resolved": { "$ref": "#/components/schemas/RangeNs" } }, "type": "object" }, "RangeNs": { "additionalProperties": false, "properties": { "end_ns": { "format": "int64", "type": "integer" }, "start_ns": { "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, "ViewTreeNode": { "additionalProperties": false, "properties": { "children": { "items": { "$ref": "#/components/schemas/ViewTreeNode" }, "type": "array" }, "display_label": { "type": "string" }, "node": { "additionalProperties": false, "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "node_id": { "format": "uuid", "type": "string" }, "parent_node": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "ref_asset": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "sort_key": { "format": "int64", "type": "integer" }, "view_id": { "format": "uuid", "type": "string" } }, "required": [ "node_id", "view_id", "parent_node", "label", "ref_asset", "sort_key" ], "type": "object" } }, "required": [ "node", "display_label", "children" ], "type": "object" }, "WindowResolved": { "additionalProperties": false, "properties": { "end_ns": { "description": "Exclusive UTC nanosecond bound.", "format": "int64", "type": "integer" }, "start_ns": { "description": "Inclusive UTC nanosecond bound.", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, "WindowSpec": { "description": "The shipped summary window union. The `kind` discriminator is snake_case.", "examples": [ { "align_ns": 0, "kind": "fixed", "len_ns": 60000000000 }, { "kind": "calendar", "timezone": "Europe/London", "unit": "day" }, { "clip": true, "include_open": true, "kind": "episodes", "role": "primary", "templates": [ "Batch" ] } ], "oneOf": [ { "additionalProperties": false, "properties": { "align_ns": { "description": "Epoch-relative alignment offset in nanoseconds; defaults to zero.", "format": "int64", "type": "integer" }, "kind": { "const": "fixed" }, "len_ns": { "description": "Positive fixed-window length in nanoseconds.", "format": "int64", "type": "integer" } }, "required": [ "kind", "len_ns" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "calendar" }, "timezone": { "description": "`utc`, `asset`, or an IANA timezone name.", "type": "string" }, "unit": { "enum": [ "hour", "day", "week", "month", "year" ], "type": "string" } }, "required": [ "kind", "unit", "timezone" ], "type": "object" }, { "additionalProperties": false, "properties": { "assets": { "type": [ "object", "null" ] }, "clip": { "default": true, "type": "boolean" }, "include_open": { "default": false, "type": "boolean" }, "kind": { "const": "episodes" }, "role": { "default": "primary", "type": "string" }, "templates": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "where": { "type": [ "string", "null" ] } }, "required": [ "kind" ], "type": "object" } ] } }, "securitySchemes": { "bearer": { "scheme": "bearer", "type": "http" }, "sessionCookie": { "in": "cookie", "name": "ordinate_session", "type": "apiKey" } } }, "info": { "description": "Executable contract transcribed from the shipped /v1 HTTP surface. UTC timestamps retain each endpoint's documented wire representation, including integer nanoseconds on legacy fields. Successful reads may honestly report provisional, lossy, quarantined, filtered, or clock-suspect data through provenance rather than converting those states into transport errors. Search ordering and relevance ranking are not contractual unless an operation explicitly says otherwise.", "license": { "identifier": "Apache-2.0", "name": "Apache-2.0" }, "title": "OrdinateDB Public API", "version": "v1" }, "openapi": "3.1.0", "paths": { "/v1/admin/change-sets": { "post": { "operationId": "post_v1_admin_change_sets", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 255, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "operations": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset.rename" ], "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "asset_id", "name" ], "type": "object" }, "maxItems": 1, "minItems": 1, "type": "array" }, "reason": { "type": "string" } }, "required": [ "reason", "operations" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "change_set_id": { "format": "uuid", "type": "string" }, "committed_ns": { "anyOf": [ { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ] }, "created_ns": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "operations": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset.rename" ], "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "asset_id", "name" ], "type": "object" }, "maxItems": 1, "minItems": 1, "type": "array" }, "preview": { "additionalProperties": false, "properties": { "changes": { "items": { "additionalProperties": false, "properties": { "after": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "name", "path" ], "type": "object" }, "base_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "before": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "name", "path" ], "type": "object" }, "resource_id": { "format": "uuid", "type": "string" }, "resource_kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "resource_kind", "resource_id", "base_tx", "before", "after" ], "type": "object" }, "type": "array" }, "summary": { "type": "string" }, "warnings": { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "summary", "changes", "warnings" ], "type": "object" }, "preview_hash": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "principal": { "type": "string" }, "reason": { "type": "string" }, "receipt": { "anyOf": [ { "additionalProperties": false, "properties": { "audit_events": { "items": { "additionalProperties": false, "properties": { "action": { "enum": [ "rename" ], "type": "string" }, "entity_id": { "format": "uuid", "type": "string" }, "entity_kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "entity_kind", "entity_id", "action" ], "type": "object" }, "type": "array" }, "committed_operations": { "items": { "additionalProperties": false, "properties": { "kind": { "enum": [ "asset.rename" ], "type": "string" }, "resource_id": { "format": "uuid", "type": "string" }, "resource_kind": { "enum": [ "asset" ], "type": "string" }, "resulting_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" } }, "required": [ "kind", "resource_kind", "resource_id", "resulting_tx" ], "type": "object" }, "type": "array" }, "model_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "operation_id": { "pattern": "^change:[0-9a-fA-F-]{36}$", "type": "string" } }, "required": [ "operation_id", "model_tx", "committed_operations", "audit_events" ], "type": "object" }, { "type": "null" } ] }, "state": { "enum": [ "preview", "committed", "cancelled", "failed" ], "type": "string" } }, "required": [ "change_set_id", "state", "reason", "operations", "preview", "preview_hash", "created_ns", "committed_ns", "principal", "receipt" ], "type": "object" } } }, "description": "Stored server-derived preview" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid request, UUID, operation, or idempotency key" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Target capability or access is denied" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Change set or target not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Preview drift, name conflict, hash mismatch, or idempotency conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Administration change-set storage failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Preview a durable administration change set", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/admin/change-sets/{id}": { "get": { "operationId": "get_v1_admin_change_sets_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "change_set_id": { "format": "uuid", "type": "string" }, "committed_ns": { "anyOf": [ { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ] }, "created_ns": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "operations": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset.rename" ], "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "asset_id", "name" ], "type": "object" }, "maxItems": 1, "minItems": 1, "type": "array" }, "preview": { "additionalProperties": false, "properties": { "changes": { "items": { "additionalProperties": false, "properties": { "after": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "name", "path" ], "type": "object" }, "base_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "before": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "name", "path" ], "type": "object" }, "resource_id": { "format": "uuid", "type": "string" }, "resource_kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "resource_kind", "resource_id", "base_tx", "before", "after" ], "type": "object" }, "type": "array" }, "summary": { "type": "string" }, "warnings": { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "summary", "changes", "warnings" ], "type": "object" }, "preview_hash": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "principal": { "type": "string" }, "reason": { "type": "string" }, "receipt": { "anyOf": [ { "additionalProperties": false, "properties": { "audit_events": { "items": { "additionalProperties": false, "properties": { "action": { "enum": [ "rename" ], "type": "string" }, "entity_id": { "format": "uuid", "type": "string" }, "entity_kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "entity_kind", "entity_id", "action" ], "type": "object" }, "type": "array" }, "committed_operations": { "items": { "additionalProperties": false, "properties": { "kind": { "enum": [ "asset.rename" ], "type": "string" }, "resource_id": { "format": "uuid", "type": "string" }, "resource_kind": { "enum": [ "asset" ], "type": "string" }, "resulting_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" } }, "required": [ "kind", "resource_kind", "resource_id", "resulting_tx" ], "type": "object" }, "type": "array" }, "model_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "operation_id": { "pattern": "^change:[0-9a-fA-F-]{36}$", "type": "string" } }, "required": [ "operation_id", "model_tx", "committed_operations", "audit_events" ], "type": "object" }, { "type": "null" } ] }, "state": { "enum": [ "preview", "committed", "cancelled", "failed" ], "type": "string" } }, "required": [ "change_set_id", "state", "reason", "operations", "preview", "preview_hash", "created_ns", "committed_ns", "principal", "receipt" ], "type": "object" } } }, "description": "Stored change set" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid request, UUID, operation, or idempotency key" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Target capability or access is denied" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Change set or target not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Preview drift, name conflict, hash mismatch, or idempotency conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Administration change-set storage failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read an administration change set", "x-ordinate-capability": "initiator-or-admin", "x-ordinate-scope": "change-set" } }, "/v1/admin/change-sets/{id}/cancel": { "post": { "operationId": "post_v1_admin_change_sets_by_id_cancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "change_set_id": { "format": "uuid", "type": "string" }, "committed_ns": { "anyOf": [ { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ] }, "created_ns": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "operations": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset.rename" ], "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "asset_id", "name" ], "type": "object" }, "maxItems": 1, "minItems": 1, "type": "array" }, "preview": { "additionalProperties": false, "properties": { "changes": { "items": { "additionalProperties": false, "properties": { "after": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "name", "path" ], "type": "object" }, "base_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "before": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "name", "path" ], "type": "object" }, "resource_id": { "format": "uuid", "type": "string" }, "resource_kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "resource_kind", "resource_id", "base_tx", "before", "after" ], "type": "object" }, "type": "array" }, "summary": { "type": "string" }, "warnings": { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "summary", "changes", "warnings" ], "type": "object" }, "preview_hash": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "principal": { "type": "string" }, "reason": { "type": "string" }, "receipt": { "anyOf": [ { "additionalProperties": false, "properties": { "audit_events": { "items": { "additionalProperties": false, "properties": { "action": { "enum": [ "rename" ], "type": "string" }, "entity_id": { "format": "uuid", "type": "string" }, "entity_kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "entity_kind", "entity_id", "action" ], "type": "object" }, "type": "array" }, "committed_operations": { "items": { "additionalProperties": false, "properties": { "kind": { "enum": [ "asset.rename" ], "type": "string" }, "resource_id": { "format": "uuid", "type": "string" }, "resource_kind": { "enum": [ "asset" ], "type": "string" }, "resulting_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" } }, "required": [ "kind", "resource_kind", "resource_id", "resulting_tx" ], "type": "object" }, "type": "array" }, "model_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "operation_id": { "pattern": "^change:[0-9a-fA-F-]{36}$", "type": "string" } }, "required": [ "operation_id", "model_tx", "committed_operations", "audit_events" ], "type": "object" }, { "type": "null" } ] }, "state": { "enum": [ "preview", "committed", "cancelled", "failed" ], "type": "string" } }, "required": [ "change_set_id", "state", "reason", "operations", "preview", "preview_hash", "created_ns", "committed_ns", "principal", "receipt" ], "type": "object" } } }, "description": "Cancelled change set" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid request, UUID, operation, or idempotency key" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Target capability or access is denied" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Change set or target not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Preview drift, name conflict, hash mismatch, or idempotency conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Administration change-set storage failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Cancel a previewed administration change set", "x-ordinate-capability": "initiator-or-admin", "x-ordinate-scope": "change-set" } }, "/v1/admin/change-sets/{id}/commit": { "post": { "operationId": "post_v1_admin_change_sets_by_id_commit", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 255, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "preview_hash": { "pattern": "^[0-9a-f]{64}$", "type": "string" } }, "required": [ "preview_hash" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "change_set_id": { "format": "uuid", "type": "string" }, "committed_ns": { "anyOf": [ { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ] }, "created_ns": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "operations": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset.rename" ], "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "asset_id", "name" ], "type": "object" }, "maxItems": 1, "minItems": 1, "type": "array" }, "preview": { "additionalProperties": false, "properties": { "changes": { "items": { "additionalProperties": false, "properties": { "after": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "name", "path" ], "type": "object" }, "base_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "before": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "name", "path" ], "type": "object" }, "resource_id": { "format": "uuid", "type": "string" }, "resource_kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "resource_kind", "resource_id", "base_tx", "before", "after" ], "type": "object" }, "type": "array" }, "summary": { "type": "string" }, "warnings": { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "summary", "changes", "warnings" ], "type": "object" }, "preview_hash": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "principal": { "type": "string" }, "reason": { "type": "string" }, "receipt": { "anyOf": [ { "additionalProperties": false, "properties": { "audit_events": { "items": { "additionalProperties": false, "properties": { "action": { "enum": [ "rename" ], "type": "string" }, "entity_id": { "format": "uuid", "type": "string" }, "entity_kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "entity_kind", "entity_id", "action" ], "type": "object" }, "type": "array" }, "committed_operations": { "items": { "additionalProperties": false, "properties": { "kind": { "enum": [ "asset.rename" ], "type": "string" }, "resource_id": { "format": "uuid", "type": "string" }, "resource_kind": { "enum": [ "asset" ], "type": "string" }, "resulting_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" } }, "required": [ "kind", "resource_kind", "resource_id", "resulting_tx" ], "type": "object" }, "type": "array" }, "model_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "operation_id": { "pattern": "^change:[0-9a-fA-F-]{36}$", "type": "string" } }, "required": [ "operation_id", "model_tx", "committed_operations", "audit_events" ], "type": "object" }, { "type": "null" } ] }, "state": { "enum": [ "preview", "committed", "cancelled", "failed" ], "type": "string" } }, "required": [ "change_set_id", "state", "reason", "operations", "preview", "preview_hash", "created_ns", "committed_ns", "principal", "receipt" ], "type": "object" } } }, "description": "Immutable commit receipt" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid request, UUID, operation, or idempotency key" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Target capability or access is denied" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Change set or target not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminChangeCommitConflict" } } }, "description": "Preview drift, state conflict, name conflict, hash mismatch, or idempotency conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Administration change-set storage failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Commit a previewed administration change set", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/annotations": { "post": { "operationId": "post_v1_annotations", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attachments": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "author": { "additionalProperties": false, "properties": { "kind": { "enum": [ "human", "system" ], "type": "string" }, "principal": { "type": "string" } }, "required": [ "kind", "principal" ], "type": "object" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "geometry": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": [ "value-line" ], "type": "string" }, "name": { "type": "string" }, "source": { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": [ "constant" ], "type": "string" }, "unit": { "type": "string" }, "value": { "type": "number" } }, "required": [ "kind", "value", "unit" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "limit-trait" ], "type": "string" }, "trait": { "type": "string" } }, "required": [ "kind", "trait" ], "type": "object" }, { "additionalProperties": false, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "attribute" ], "type": "string" } }, "required": [ "kind", "attribute_id" ], "type": "object" } ] } }, "required": [ "kind", "source" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "point-marker" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "region" ], "type": "string" }, "time": { "anyOf": [ { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, { "type": "null" } ] }, "value": { "anyOf": [ { "additionalProperties": false, "properties": { "max": { "type": "number" }, "min": { "type": "number" }, "unit": { "type": "string" } }, "required": [ "min", "max", "unit" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "kind" ], "type": "object" } ] }, { "type": "null" } ] }, "reason": { "type": "string" }, "reply_to": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "target": { "additionalProperties": false, "properties": { "urn": { "type": "string" } }, "required": [ "urn" ], "type": "object" } }, "required": [ "target", "author" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "id", "version" ], "type": "object" } } }, "description": "Created annotation identity" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Malformed annotation, target, tag, or geometry" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "annotate capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Create an annotation", "x-ordinate-capability": "annotate", "x-ordinate-scope": "handler-resolved target" } }, "/v1/annotations/attachments": { "post": { "operationId": "post_v1_annotations_attachments", "parameters": [ { "in": "query", "name": "name", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "mime", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attachment_id": { "format": "uuid", "type": "string" }, "content_hash": { "type": "string" }, "deduplicated": { "type": "boolean" }, "size_bytes": { "format": "int64", "type": "integer" } }, "required": [ "attachment_id", "size_bytes", "content_hash", "deduplicated" ], "type": "object" } } }, "description": "Content-addressed upload receipt" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing upload metadata" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "annotate capability is not granted" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Attachment exceeds configured byte cap" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Upload an annotation attachment", "x-ordinate-capability": "annotate", "x-ordinate-scope": "handler-resolved target" } }, "/v1/annotations/attachments/{id}": { "get": { "operationId": "get_v1_annotations_attachments_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "Stored attachment bytes with the original Content-Type" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid attachment id" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Attachment not found" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Attachment bytes were redacted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Download an annotation attachment", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" } }, "/v1/annotations/query": { "post": { "operationId": "post_v1_annotations_query", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "authors": { "items": { "additionalProperties": false, "properties": { "kind": { "enum": [ "human", "system" ], "type": "string" }, "principal": { "type": "string" } }, "required": [ "kind", "principal" ], "type": "object" }, "type": "array" }, "cluster": { "additionalProperties": false, "properties": { "range": { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, "width_px": { "format": "int64", "type": "integer" } }, "required": [ "width_px", "range" ], "type": "object" }, "cursor": { "type": "string" }, "event_time": { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, "include_replies": { "type": "boolean" }, "limit": { "format": "int64", "type": "integer" }, "record_time": { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, "return": { "enum": [ "annotations", "counts" ], "type": "string" }, "subtree": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" } }, "required": [ "asset_id" ], "type": "object" }, "tags": { "items": { "type": "string" }, "type": "array" }, "target_types": { "items": { "type": "string" }, "type": "array" }, "targets": { "items": { "type": "string" }, "type": "array" }, "text": { "type": "string" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "annotations": { "items": { "additionalProperties": false, "properties": { "attachments": { "items": { "additionalProperties": false, "properties": { "attachment_id": { "format": "uuid", "type": "string" }, "content_hash": { "type": "string" }, "mime": { "type": "string" }, "name": { "type": "string" }, "redacted": { "type": "boolean" }, "size_bytes": { "format": "int64", "type": "integer" } }, "required": [ "attachment_id", "name", "mime", "size_bytes", "content_hash", "redacted" ], "type": "object" }, "type": "array" }, "author": { "additionalProperties": false, "properties": { "kind": { "enum": [ "human", "system" ], "type": "string" }, "principal": { "type": "string" } }, "required": [ "kind", "principal" ], "type": "object" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "edited_at_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "event_time": { "anyOf": [ { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, { "type": "null" } ] }, "geometry": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": [ "value-line" ], "type": "string" }, "name": { "type": "string" }, "source": { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": [ "constant" ], "type": "string" }, "unit": { "type": "string" }, "value": { "type": "number" } }, "required": [ "kind", "value", "unit" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "limit-trait" ], "type": "string" }, "trait": { "type": "string" } }, "required": [ "kind", "trait" ], "type": "object" }, { "additionalProperties": false, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "attribute" ], "type": "string" } }, "required": [ "kind", "attribute_id" ], "type": "object" } ] } }, "required": [ "kind", "source" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "point-marker" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "region" ], "type": "string" }, "time": { "anyOf": [ { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, { "type": "null" } ] }, "value": { "anyOf": [ { "additionalProperties": false, "properties": { "max": { "type": "number" }, "min": { "type": "number" }, "unit": { "type": "string" } }, "required": [ "min", "max", "unit" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "kind" ], "type": "object" } ] }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "create", "edit", "redaction" ], "type": "string" }, "redacted": { "type": "boolean" }, "replies": { "items": { "additionalProperties": false, "properties": { "attachments": { "items": { "additionalProperties": false, "properties": { "attachment_id": { "format": "uuid", "type": "string" }, "content_hash": { "type": "string" }, "mime": { "type": "string" }, "name": { "type": "string" }, "redacted": { "type": "boolean" }, "size_bytes": { "format": "int64", "type": "integer" } }, "required": [ "attachment_id", "name", "mime", "size_bytes", "content_hash", "redacted" ], "type": "object" }, "type": "array" }, "author": { "additionalProperties": false, "properties": { "kind": { "enum": [ "human", "system" ], "type": "string" }, "principal": { "type": "string" } }, "required": [ "kind", "principal" ], "type": "object" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "edited_at_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "event_time": { "anyOf": [ { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, { "type": "null" } ] }, "geometry": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": [ "value-line" ], "type": "string" }, "name": { "type": "string" }, "source": { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": [ "constant" ], "type": "string" }, "unit": { "type": "string" }, "value": { "type": "number" } }, "required": [ "kind", "value", "unit" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "limit-trait" ], "type": "string" }, "trait": { "type": "string" } }, "required": [ "kind", "trait" ], "type": "object" }, { "additionalProperties": false, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "attribute" ], "type": "string" } }, "required": [ "kind", "attribute_id" ], "type": "object" } ] } }, "required": [ "kind", "source" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "point-marker" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "region" ], "type": "string" }, "time": { "anyOf": [ { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, { "type": "null" } ] }, "value": { "anyOf": [ { "additionalProperties": false, "properties": { "max": { "type": "number" }, "min": { "type": "number" }, "unit": { "type": "string" } }, "required": [ "min", "max", "unit" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "kind" ], "type": "object" } ] }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "create", "edit", "redaction" ], "type": "string" }, "redacted": { "type": "boolean" }, "reply_to": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "target": { "additionalProperties": false, "properties": { "urn": { "type": "string" } }, "required": [ "urn" ], "type": "object" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "id", "target", "author", "created_at_ns", "version", "kind", "body", "tags", "attachments", "reply_to", "geometry", "event_time", "redacted", "edited_at_ns" ], "type": "object" }, "type": "array" }, "reply_to": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "target": { "additionalProperties": false, "properties": { "urn": { "type": "string" } }, "required": [ "urn" ], "type": "object" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "id", "target", "author", "created_at_ns", "version", "kind", "body", "tags", "attachments", "reply_to", "geometry", "event_time", "redacted", "edited_at_ns" ], "type": "object" }, "type": "array" }, "clusters": { "anyOf": [ { "items": { "additionalProperties": true, "properties": {}, "required": [], "type": "object" }, "type": "array" }, { "type": "null" } ] }, "counts": { "anyOf": [ { "items": { "additionalProperties": true, "properties": {}, "required": [], "type": "object" }, "type": "array" }, { "type": "null" } ] }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "annotations", "clusters", "counts", "next_cursor" ], "type": "object" } } }, "description": "Filtered annotations, counts, or clusters" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Malformed query, selector, target, or cursor" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Query annotations", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" } }, "/v1/annotations/{id}": { "get": { "operationId": "get_v1_annotations_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "include_replies", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attachments": { "items": { "additionalProperties": false, "properties": { "attachment_id": { "format": "uuid", "type": "string" }, "content_hash": { "type": "string" }, "mime": { "type": "string" }, "name": { "type": "string" }, "redacted": { "type": "boolean" }, "size_bytes": { "format": "int64", "type": "integer" } }, "required": [ "attachment_id", "name", "mime", "size_bytes", "content_hash", "redacted" ], "type": "object" }, "type": "array" }, "author": { "additionalProperties": false, "properties": { "kind": { "enum": [ "human", "system" ], "type": "string" }, "principal": { "type": "string" } }, "required": [ "kind", "principal" ], "type": "object" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "edited_at_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "event_time": { "anyOf": [ { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, { "type": "null" } ] }, "geometry": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": [ "value-line" ], "type": "string" }, "name": { "type": "string" }, "source": { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": [ "constant" ], "type": "string" }, "unit": { "type": "string" }, "value": { "type": "number" } }, "required": [ "kind", "value", "unit" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "limit-trait" ], "type": "string" }, "trait": { "type": "string" } }, "required": [ "kind", "trait" ], "type": "object" }, { "additionalProperties": false, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "attribute" ], "type": "string" } }, "required": [ "kind", "attribute_id" ], "type": "object" } ] } }, "required": [ "kind", "source" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "point-marker" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "region" ], "type": "string" }, "time": { "anyOf": [ { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, { "type": "null" } ] }, "value": { "anyOf": [ { "additionalProperties": false, "properties": { "max": { "type": "number" }, "min": { "type": "number" }, "unit": { "type": "string" } }, "required": [ "min", "max", "unit" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "kind" ], "type": "object" } ] }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "create", "edit", "redaction" ], "type": "string" }, "redacted": { "type": "boolean" }, "replies": { "items": { "additionalProperties": false, "properties": { "attachments": { "items": { "additionalProperties": false, "properties": { "attachment_id": { "format": "uuid", "type": "string" }, "content_hash": { "type": "string" }, "mime": { "type": "string" }, "name": { "type": "string" }, "redacted": { "type": "boolean" }, "size_bytes": { "format": "int64", "type": "integer" } }, "required": [ "attachment_id", "name", "mime", "size_bytes", "content_hash", "redacted" ], "type": "object" }, "type": "array" }, "author": { "additionalProperties": false, "properties": { "kind": { "enum": [ "human", "system" ], "type": "string" }, "principal": { "type": "string" } }, "required": [ "kind", "principal" ], "type": "object" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "edited_at_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "event_time": { "anyOf": [ { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, { "type": "null" } ] }, "geometry": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": [ "value-line" ], "type": "string" }, "name": { "type": "string" }, "source": { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": [ "constant" ], "type": "string" }, "unit": { "type": "string" }, "value": { "type": "number" } }, "required": [ "kind", "value", "unit" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "limit-trait" ], "type": "string" }, "trait": { "type": "string" } }, "required": [ "kind", "trait" ], "type": "object" }, { "additionalProperties": false, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "attribute" ], "type": "string" } }, "required": [ "kind", "attribute_id" ], "type": "object" } ] } }, "required": [ "kind", "source" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "point-marker" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "region" ], "type": "string" }, "time": { "anyOf": [ { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, { "type": "null" } ] }, "value": { "anyOf": [ { "additionalProperties": false, "properties": { "max": { "type": "number" }, "min": { "type": "number" }, "unit": { "type": "string" } }, "required": [ "min", "max", "unit" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "kind" ], "type": "object" } ] }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "create", "edit", "redaction" ], "type": "string" }, "redacted": { "type": "boolean" }, "reply_to": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "target": { "additionalProperties": false, "properties": { "urn": { "type": "string" } }, "required": [ "urn" ], "type": "object" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "id", "target", "author", "created_at_ns", "version", "kind", "body", "tags", "attachments", "reply_to", "geometry", "event_time", "redacted", "edited_at_ns" ], "type": "object" }, "type": "array" }, "reply_to": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "tags": { "items": { "type": "string" }, "type": "array" }, "target": { "additionalProperties": false, "properties": { "urn": { "type": "string" } }, "required": [ "urn" ], "type": "object" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "id", "target", "author", "created_at_ns", "version", "kind", "body", "tags", "attachments", "reply_to", "geometry", "event_time", "redacted", "edited_at_ns" ], "type": "object" } } }, "description": "Current annotation version" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid annotation id" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Annotation not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read an annotation", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" }, "put": { "operationId": "put_v1_annotations_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attachments": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "author": { "additionalProperties": false, "properties": { "kind": { "enum": [ "human", "system" ], "type": "string" }, "principal": { "type": "string" } }, "required": [ "kind", "principal" ], "type": "object" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "geometry": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": [ "value-line" ], "type": "string" }, "name": { "type": "string" }, "source": { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "enum": [ "constant" ], "type": "string" }, "unit": { "type": "string" }, "value": { "type": "number" } }, "required": [ "kind", "value", "unit" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "limit-trait" ], "type": "string" }, "trait": { "type": "string" } }, "required": [ "kind", "trait" ], "type": "object" }, { "additionalProperties": false, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "attribute" ], "type": "string" } }, "required": [ "kind", "attribute_id" ], "type": "object" } ] } }, "required": [ "kind", "source" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "point-marker" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "region" ], "type": "string" }, "time": { "anyOf": [ { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, { "type": "null" } ] }, "value": { "anyOf": [ { "additionalProperties": false, "properties": { "max": { "type": "number" }, "min": { "type": "number" }, "unit": { "type": "string" } }, "required": [ "min", "max", "unit" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "kind" ], "type": "object" } ] }, { "type": "null" } ] }, "reason": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" } }, "required": [ "author" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "version": { "format": "int64", "type": "integer" } }, "required": [ "version" ], "type": "object" } } }, "description": "New annotation version" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Malformed edit or attempted immutable target/reply change" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "annotate capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Annotation not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Edit an annotation", "x-ordinate-capability": "annotate", "x-ordinate-scope": "handler-resolved target" } }, "/v1/annotations/{id}/redact": { "post": { "operationId": "post_v1_annotations_by_id_redact", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "author": { "additionalProperties": false, "properties": { "kind": { "enum": [ "human", "system" ], "type": "string" }, "principal": { "type": "string" } }, "required": [ "kind", "principal" ], "type": "object" }, "reason": { "type": "string" }, "scope": { "enum": [ "body", "body+attachments" ], "type": "string" } }, "required": [ "reason", "scope" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "version": { "format": "int64", "type": "integer" } }, "required": [ "version" ], "type": "object" } } }, "description": "New redaction version" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Malformed redaction" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "redact capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Annotation not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Redact annotation content", "x-ordinate-capability": "redact", "x-ordinate-scope": "handler-resolved target" } }, "/v1/annotations/{id}/versions": { "get": { "operationId": "get_v1_annotations_by_id_versions", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "versions": { "items": { "additionalProperties": true, "properties": {}, "required": [], "type": "object" }, "type": "array" } }, "required": [ "versions" ], "type": "object" } } }, "description": "Version history including redaction reasons" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid annotation id" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Annotation not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List annotation versions", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" } }, "/v1/auth/callback": { "get": { "operationId": "get_v1_auth_callback", "parameters": [ { "in": "query", "name": "code", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "state", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Session created; redirect includes an HttpOnly session cookie" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing, unknown, or expired callback state" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Token exchange or verification failed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "OIDC is not configured" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "security": [], "summary": "Complete OIDC login", "x-ordinate-capability": "anonymous", "x-ordinate-scope": "none" } }, "/v1/auth/effective": { "post": { "operationId": "post_v1_auth_effective", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "as_of_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "capability": { "$ref": "#/components/schemas/Capability" }, "principal": { "anyOf": [ { "$ref": "#/components/schemas/PrincipalString" }, { "type": "null" } ] }, "scope_id": { "format": "uuid", "type": "string" }, "scope_kind": { "enum": [ "site", "area", "unit", "asset" ], "type": "string" } }, "required": [ "capability", "scope_kind", "scope_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "allowed": { "type": "boolean" }, "derivation": { "items": { "type": "object" }, "type": "array" }, "group_membership": { "enum": [ "as-asserted-now" ], "type": "string" }, "snapshot_built_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "allowed", "derivation", "snapshot_built_at_ns" ], "type": "object" } } }, "description": "Decision from the same evaluator used for enforcement" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid decision request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Admin capability required for another principal" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "Explain an effective authorization decision", "x-ordinate-capability": "authenticated", "x-ordinate-scope": "self, or any principal with admin" } }, "/v1/auth/grants": { "get": { "operationId": "get_v1_auth_grants", "parameters": [ { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "entries": { "items": { "additionalProperties": false, "properties": { "grant_id": { "format": "uuid", "type": "string" }, "principal": { "$ref": "#/components/schemas/PrincipalString" }, "role_id": { "format": "uuid", "type": "string" }, "scope_id": { "format": "uuid", "type": "string" }, "scope_kind": { "enum": [ "site", "area", "unit", "asset" ], "type": "string" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "valid_to_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "grant_id", "principal", "role_id", "scope_kind", "scope_id", "valid_from_ns", "valid_to_ns", "tx_id" ], "type": "object" }, "type": "array" } }, "required": [ "entries" ], "type": "object" } } }, "description": "Grants" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Required capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "List authorization grants", "x-ordinate-capability": "admin", "x-ordinate-scope": "handler-resolved target" }, "post": { "operationId": "post_v1_auth_grants", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "principal": { "$ref": "#/components/schemas/PrincipalString" }, "role_id": { "format": "uuid", "type": "string" }, "scope_id": { "format": "uuid", "type": "string" }, "scope_kind": { "enum": [ "site", "area", "unit", "asset" ], "type": "string" } }, "required": [ "principal", "role_id", "scope_kind", "scope_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "grant_id": { "format": "uuid", "type": "string" }, "principal": { "$ref": "#/components/schemas/PrincipalString" }, "role_id": { "format": "uuid", "type": "string" }, "scope_id": { "format": "uuid", "type": "string" }, "scope_kind": { "enum": [ "site", "area", "unit", "asset" ], "type": "string" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "valid_to_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "grant_id", "principal", "role_id", "scope_kind", "scope_id", "valid_from_ns", "valid_to_ns", "tx_id" ], "type": "object" } } }, "description": "Grant created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid grant" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Required capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Grant conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "Create an authorization grant", "x-ordinate-capability": "admin", "x-ordinate-scope": "handler-resolved target" } }, "/v1/auth/grants/{id}": { "delete": { "operationId": "delete_v1_auth_grants_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Grant retired" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid grant id" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Required capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Grant not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "Retire an authorization grant", "x-ordinate-capability": "admin", "x-ordinate-scope": "handler-resolved target" } }, "/v1/auth/login": { "get": { "operationId": "get_v1_auth_login", "parameters": [ { "in": "query", "name": "redirect", "required": false, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to the configured identity provider" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Redirect is not a local path" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "OIDC is not configured" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "OIDC discovery failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "security": [], "summary": "Begin OIDC authorization-code login", "x-ordinate-capability": "anonymous", "x-ordinate-scope": "none" } }, "/v1/auth/login/local": { "post": { "operationId": "post_v1_auth_login_local", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "password": { "format": "password", "type": "string", "writeOnly": true }, "username": { "type": "string" } }, "required": [ "username", "password" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "Session created; response sets the HttpOnly session cookie" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid credentials" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Account is sealed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "security": [], "summary": "Sign in with local credentials", "x-ordinate-capability": "anonymous", "x-ordinate-scope": "none" } }, "/v1/auth/logout": { "post": { "operationId": "post_v1_auth_logout", "responses": { "204": { "description": "Session revoked and cookie cleared" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "Revoke the current session", "x-ordinate-capability": "authenticated", "x-ordinate-scope": "current session" } }, "/v1/auth/methods": { "get": { "operationId": "get_v1_auth_methods", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "auth_mode": { "enum": [ "disabled", "shadow", "enforced" ], "type": "string" }, "login_methods": { "items": { "enum": [ "local", "oidc" ], "type": "string" }, "type": "array", "uniqueItems": true } }, "required": [ "auth_mode", "login_methods" ], "type": "object" } } }, "description": "Bounded authentication discovery without provider configuration" } }, "security": [], "summary": "Discover configured authentication methods", "x-ordinate-capability": "anonymous", "x-ordinate-scope": "none" } }, "/v1/auth/principals": { "get": { "operationId": "get_v1_auth_principals", "parameters": [ { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "entries": { "items": { "additionalProperties": false, "properties": { "disabled": { "type": "boolean" }, "display": { "type": "string" }, "kind": { "type": "string" }, "principal_id": { "format": "uuid", "type": "string" }, "subject": { "type": "string" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "valid_to_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "principal_id", "kind", "subject", "display", "disabled", "valid_from_ns", "valid_to_ns", "tx_id" ], "type": "object" }, "type": "array" } }, "required": [ "entries" ], "type": "object" } } }, "description": "Principals" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Required capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "List principals", "x-ordinate-capability": "admin", "x-ordinate-scope": "handler-resolved target" }, "post": { "operationId": "post_v1_auth_principals", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "display": { "type": "string" }, "password": { "format": "password", "type": "string", "writeOnly": true }, "username": { "type": "string" } }, "required": [ "username", "password" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "disabled": { "type": "boolean" }, "display": { "type": "string" }, "kind": { "type": "string" }, "principal_id": { "format": "uuid", "type": "string" }, "subject": { "type": "string" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "valid_to_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "principal_id", "kind", "subject", "display", "disabled", "valid_from_ns", "valid_to_ns", "tx_id" ], "type": "object" } } }, "description": "Principal created; credentials are never returned" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid principal" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Required capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Username already exists" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "Create a local human principal", "x-ordinate-capability": "admin", "x-ordinate-scope": "handler-resolved target" } }, "/v1/auth/roles": { "get": { "operationId": "get_v1_auth_roles", "parameters": [ { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "entries": { "items": { "additionalProperties": false, "properties": { "capabilities": { "items": { "$ref": "#/components/schemas/Capability" }, "type": "array" }, "name": { "type": "string" }, "role_id": { "format": "uuid", "type": "string" }, "system": { "type": "boolean" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "valid_to_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "role_id", "name", "capabilities", "system", "valid_from_ns", "valid_to_ns", "tx_id" ], "type": "object" }, "type": "array" } }, "required": [ "entries" ], "type": "object" } } }, "description": "Roles" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Required capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "List authorization roles", "x-ordinate-capability": "admin", "x-ordinate-scope": "handler-resolved target" }, "post": { "operationId": "post_v1_auth_roles", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "capabilities": { "items": { "$ref": "#/components/schemas/Capability" }, "type": "array" }, "name": { "type": "string" } }, "required": [ "name", "capabilities" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "capabilities": { "items": { "$ref": "#/components/schemas/Capability" }, "type": "array" }, "name": { "type": "string" }, "role_id": { "format": "uuid", "type": "string" }, "system": { "type": "boolean" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "valid_to_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "role_id", "name", "capabilities", "system", "valid_from_ns", "valid_to_ns", "tx_id" ], "type": "object" } } }, "description": "Role created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid role" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Required capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Role name already exists" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "Create an authorization role", "x-ordinate-capability": "admin", "x-ordinate-scope": "handler-resolved target" } }, "/v1/auth/roles/{id}": { "get": { "operationId": "get_v1_auth_roles_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "capabilities": { "items": { "$ref": "#/components/schemas/Capability" }, "type": "array" }, "name": { "type": "string" }, "role_id": { "format": "uuid", "type": "string" }, "system": { "type": "boolean" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "valid_to_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "role_id", "name", "capabilities", "system", "valid_from_ns", "valid_to_ns", "tx_id" ], "type": "object" } } }, "description": "Role" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid role id" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Required capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Role not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "Read an authorization role", "x-ordinate-capability": "admin", "x-ordinate-scope": "handler-resolved target" }, "put": { "operationId": "put_v1_auth_roles_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "capabilities": { "items": { "$ref": "#/components/schemas/Capability" }, "type": "array" }, "expected_tx": { "format": "int64", "type": "integer" }, "name": { "type": "string" }, "retired": { "type": "boolean" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "capabilities": { "items": { "$ref": "#/components/schemas/Capability" }, "type": "array" }, "name": { "type": "string" }, "role_id": { "format": "uuid", "type": "string" }, "system": { "type": "boolean" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "valid_to_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "role_id", "name", "capabilities", "system", "valid_from_ns", "valid_to_ns", "tx_id" ], "type": "object" } } }, "description": "Updated role" }, "204": { "description": "Role retired" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Required capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Role not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Transaction conflict or duplicate name" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "Update or retire an authorization role", "x-ordinate-capability": "admin", "x-ordinate-scope": "handler-resolved target" } }, "/v1/auth/service-identities": { "get": { "operationId": "get_v1_auth_service_identities", "parameters": [ { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "entries": { "items": { "additionalProperties": false, "properties": { "disabled": { "type": "boolean" }, "kind": { "type": "string" }, "name": { "type": "string" }, "service_id": { "format": "uuid", "type": "string" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "valid_to_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "service_id", "kind", "name", "disabled", "valid_from_ns", "valid_to_ns", "tx_id" ], "type": "object" }, "type": "array" } }, "required": [ "entries" ], "type": "object" } } }, "description": "Service identities" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Required capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "List service identities", "x-ordinate-capability": "admin", "x-ordinate-scope": "handler-resolved target" }, "post": { "operationId": "post_v1_auth_service_identities", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "kind": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "disabled": { "type": "boolean" }, "kind": { "type": "string" }, "name": { "type": "string" }, "service_id": { "format": "uuid", "type": "string" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "valid_to_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "service_id", "kind", "name", "disabled", "valid_from_ns", "valid_to_ns", "tx_id" ], "type": "object" } } }, "description": "Service identity created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid service identity" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Required capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Name already exists" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "Create a service identity", "x-ordinate-capability": "admin", "x-ordinate-scope": "handler-resolved target" } }, "/v1/auth/service-identities/tokens/{token_id}/revoke": { "post": { "operationId": "post_v1_auth_service_identities_tokens_by_token_id_revoke", "parameters": [ { "in": "path", "name": "token_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Service token revoked" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid token id" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Required capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Token not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "Revoke a service token", "x-ordinate-capability": "admin", "x-ordinate-scope": "handler-resolved target" } }, "/v1/auth/service-identities/{id}/tokens": { "post": { "operationId": "post_v1_auth_service_identities_by_id_tokens", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "comment": { "type": "string" }, "expires_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "rotate": { "type": "boolean" } }, "required": [ "expires_at_ns" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expires_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "issued_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "service_id": { "format": "uuid", "type": "string" }, "token": { "description": "One-time plaintext secret returned only by this mint operation", "type": "string", "x-one-time-secret": true }, "token_id": { "format": "uuid", "type": "string" } }, "required": [ "token", "token_id", "service_id", "issued_at_ns", "expires_at_ns" ], "type": "object" } } }, "description": "One-time plaintext token; it cannot be retrieved again" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid token request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Required capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Too many active tokens" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "Mint or rotate a service token", "x-ordinate-capability": "admin", "x-ordinate-scope": "handler-resolved target" } }, "/v1/auth/sessions": { "get": { "operationId": "get_v1_auth_sessions", "parameters": [ { "in": "query", "name": "all", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "entries": { "items": { "additionalProperties": false, "properties": { "absolute_expiry_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "created_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "id": { "type": "string" }, "last_seen_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "principal_id": { "format": "uuid", "type": "string" } }, "required": [ "id", "principal_id", "created_at_ns", "last_seen_ns", "absolute_expiry_ns" ], "type": "object" }, "type": "array" } }, "required": [ "entries" ], "type": "object" } } }, "description": "Sessions" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Sessions are only available for human principals" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Admin capability required for all sessions" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "List the caller's sessions or all sessions", "x-ordinate-capability": "authenticated", "x-ordinate-scope": "self, or all sessions with admin when all=true" } }, "/v1/auth/sessions/{id}": { "delete": { "operationId": "delete_v1_auth_sessions_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Session revoked" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Admin capability required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Session not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "summary": "Revoke a session as an administrator", "x-ordinate-capability": "admin", "x-ordinate-scope": "handler-resolved target" } }, "/v1/auth/whoami": { "get": { "operationId": "get_v1_auth_whoami", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "auth_mode": { "enum": [ "disabled", "shadow", "enforced" ], "type": "string" }, "authorization_model_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "authorization_snapshot_built_at_ns": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "capability_catalog_version": { "minimum": 1, "type": "integer" }, "display": { "type": "string" }, "effective_capabilities": { "items": { "description": "Extensible capability token. Unknown future tokens remain parseable but do not enable controls the client does not understand.", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$", "type": "string" }, "type": "array", "uniqueItems": true }, "groups": { "items": { "type": "string" }, "type": "array" }, "kind": { "type": "string" }, "login_methods": { "items": { "enum": [ "local", "oidc" ], "type": "string" }, "type": "array", "uniqueItems": true }, "principal": { "$ref": "#/components/schemas/PrincipalString" }, "roles": { "items": { "additionalProperties": false, "properties": { "role": { "type": "string" }, "scope_id": { "format": "uuid", "type": "string" }, "scope_kind": { "type": "string" } }, "required": [ "role", "scope_kind", "scope_id" ], "type": "object" }, "type": "array" }, "session_expires_at_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "session_expires_at_ns_exact": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": [ "string", "null" ] } }, "required": [ "principal", "display", "kind", "groups", "roles", "session_expires_at_ns", "session_expires_at_ns_exact", "effective_capabilities", "authorization_snapshot_built_at_ns", "authorization_model_tx", "capability_catalog_version", "auth_mode", "login_methods" ], "type": "object" } } }, "description": "Authenticated principal and direct roles" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Principal not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or authorization snapshot is unavailable" } }, "summary": "Describe the authenticated principal", "x-ordinate-capability": "authenticated", "x-ordinate-scope": "self" } }, "/v1/calc/backfill": { "post": { "operationId": "post_v1_calc_backfill", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "description": "Replays the first successful response for the same authenticated principal, route, key, and request body", "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "asset_ids": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "preview": { "type": "boolean" }, "rule_id": { "format": "uuid", "type": "string" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "rule_id", "start_ns", "end_ns" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "job_id": { "format": "uuid", "type": "string" } }, "required": [ "job_id" ], "type": "object" } } }, "description": "Backfill accepted", "headers": { "X-Ordinate-Idempotent-Replay": { "description": "Present with the literal value `true` when this response was replayed", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "end_ns must be greater than start_ns; Invalid or oversized Idempotency-Key" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "calc-author capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Idempotency-Key was already used with a different request body" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Create a calculation backfill", "x-ordinate-capability": "calc-author", "x-ordinate-scope": "handler-resolved target" } }, "/v1/calc/backfill/{job_id}": { "get": { "operationId": "get_v1_calc_backfill_by_job_id", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "job_id": { "format": "uuid", "type": "string" }, "preview": { "anyOf": [ { "additionalProperties": false, "properties": { "points_added": { "format": "int64", "type": "integer" }, "points_changed": { "format": "int64", "type": "integer" }, "points_unchanged": { "format": "int64", "type": "integer" }, "sample": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "new": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "old": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "ts_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "asset_id", "ts_ns", "old", "new" ], "type": "object" }, "type": "array" } }, "required": [ "points_added", "points_changed", "points_unchanged", "sample" ], "type": "object" }, { "type": "null" } ] }, "progress": { "additionalProperties": false, "properties": { "points_written": { "format": "int64", "type": "integer" }, "rate_limited_ms": { "format": "int64", "type": "integer" }, "windows_done": { "format": "int64", "type": "integer" }, "windows_total": { "format": "int64", "type": "integer" } }, "required": [ "windows_total", "windows_done", "points_written", "rate_limited_ms" ], "type": "object" }, "state": { "type": "string" } }, "required": [ "job_id", "state", "progress", "preview" ], "type": "object" } } }, "description": "Backfill view" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Backfill not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read calculation backfill progress", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" } }, "/v1/calc/backfill/{job_id}/cancel": { "post": { "operationId": "post_v1_calc_backfill_by_job_id_cancel", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "job_id": { "format": "uuid", "type": "string" }, "state": { "type": "string" } }, "required": [ "job_id", "state" ], "type": "object" } } }, "description": "Cancellation receipt" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "calc-author capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Backfill cannot be cancelled in its current state" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Cancel a calculation backfill", "x-ordinate-capability": "calc-author", "x-ordinate-scope": "handler-resolved target" } }, "/v1/calc/backfill/{job_id}/commit": { "post": { "operationId": "post_v1_calc_backfill_by_job_id_commit", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "job_id": { "format": "uuid", "type": "string" }, "state": { "enum": [ "pending" ], "type": "string" } }, "required": [ "job_id", "state" ], "type": "object" } } }, "description": "Backfill moved to pending" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "calc-author capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Backfill is not awaiting commit" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Commit a preview calculation backfill", "x-ordinate-capability": "calc-author", "x-ordinate-scope": "handler-resolved target" } }, "/v1/calc/lineage": { "get": { "operationId": "get_v1_calc_lineage", "parameters": [ { "in": "query", "name": "series", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "ts_ns", "required": true, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "evaluated_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "inputs": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "rule_id": { "format": "uuid", "type": "string" }, "rule_version": { "format": "int64", "type": "integer" }, "window": { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" } }, "required": [ "rule_id", "rule_version", "window", "evaluated_at_ns", "inputs" ], "type": "object" } } }, "description": "Covering evaluation with latest computed_at_ns" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No lineage covers this series instant" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read calculation lineage at a series instant", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" } }, "/v1/calc/rules/{rule_id}/status": { "get": { "operationId": "get_v1_calc_rules_by_rule_id_status", "parameters": [ { "in": "path", "name": "rule_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "instances": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "consecutive_failures": { "format": "int64", "type": "integer" }, "frontier_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "last_eval_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "output_series": { "format": "uuid", "type": "string" }, "provisional_windows": { "items": { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, "type": "array" }, "state": { "type": "string" } }, "required": [ "asset_id", "output_series", "state", "frontier_ns", "last_eval_ns", "consecutive_failures", "provisional_windows" ], "type": "object" }, "type": "array" }, "rule_id": { "format": "uuid", "type": "string" } }, "required": [ "rule_id", "instances" ], "type": "object" } } }, "description": "Per-instance runtime status" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read calculation instance health", "x-honest-oddity": "A rule can expand to many assets; this ledger-only status route is coarse any-Read", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" } }, "/v1/calc/rules/{rule_id}/trace": { "get": { "operationId": "get_v1_calc_rules_by_rule_id_trace", "parameters": [ { "in": "path", "name": "rule_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "asset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "start_ns", "required": true, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, { "in": "query", "name": "end_ns", "required": true, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "evaluations": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "computed_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "eval_instant_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "inputs": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "outcome": { "type": "string" }, "output_series": { "format": "uuid", "type": "string" }, "provisional": { "type": "boolean" }, "quality": { "anyOf": [ { "format": "int64", "type": "integer" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rule_version": { "format": "int64", "type": "integer" }, "trigger": { "type": "string" }, "value": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "window": { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" } }, "required": [ "asset_id", "output_series", "window", "eval_instant_ns", "rule_version", "trigger", "outcome", "value", "quality", "reason", "provisional", "computed_at_ns", "inputs" ], "type": "object" }, "type": "array" } }, "required": [ "evaluations" ], "type": "object" } } }, "description": "Recorded evaluations" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read calculation evaluation trace", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" } }, "/v1/collectors": { "get": { "operationId": "get_v1_collectors", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": false, "properties": { "acked_through": { "minimum": 0, "type": "integer" }, "collector_id": { "type": "string" }, "credit_backfill": { "minimum": 0, "type": "integer" }, "credit_live": { "minimum": 0, "type": "integer" }, "fenced_streams_total": { "minimum": 0, "type": "integer" }, "last_batch_arrival_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "last_collector_receipt_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "last_fenced_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "session_epoch": { "minimum": 0, "type": "integer" }, "streams": { "items": { "type": "string" }, "type": "array" }, "watermark_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "collector_id", "session_epoch", "streams", "last_batch_arrival_ns", "last_collector_receipt_ns", "watermark_ns", "acked_through", "credit_live", "credit_backfill", "fenced_streams_total", "last_fenced_ns" ], "type": "object" }, "type": "array" } } }, "description": "Collector diagnostics" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" } }, "summary": "List collector connection diagnostics", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" } }, "/v1/display-folders": { "get": { "operationId": "get_v1_display_folders", "parameters": [ { "in": "query", "name": "parent", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": false, "properties": { "folder_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "parent_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "folder_id", "parent_id", "name", "tx_id" ], "type": "object" }, "type": "array" } } }, "description": "Folders directly beneath the selected parent" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List child display folders", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" }, "post": { "operationId": "post_v1_display_folders", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "description": "Replays the first successful response for the same authenticated principal, route, key, and request body", "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "parent_id": { "format": "uuid", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "folder_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "parent_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "folder_id", "parent_id", "name", "tx_id" ], "type": "object" } } }, "description": "Created folder", "headers": { "X-Ordinate-Idempotent-Replay": { "description": "Present with the literal value `true` when this response was replayed", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid folder; Invalid or oversized Idempotency-Key" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "display-author capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Folder name conflict; Idempotency-Key was already used with a different request body" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Create a display folder", "x-ordinate-capability": "display-author", "x-ordinate-scope": "handler-resolved target" } }, "/v1/display-folders/{id}": { "get": { "operationId": "get_v1_display_folders_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "folder_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "parent_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "folder_id", "parent_id", "name", "tx_id" ], "type": "object" } } }, "description": "Display folder" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Folder not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read a display folder", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" }, "put": { "operationId": "put_v1_display_folders_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expected_tx": { "format": "int64", "type": "integer" }, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "folder_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "parent_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "folder_id", "parent_id", "name", "tx_id" ], "type": "object" } } }, "description": "Renamed folder" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "display-author capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Folder not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Name or transaction conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Rename a display folder", "x-ordinate-capability": "display-author", "x-ordinate-scope": "handler-resolved target" } }, "/v1/displays": { "get": { "operationId": "get_v1_displays", "parameters": [ { "in": "query", "name": "folder", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "kind", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "after", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "description": "Opaque keyset cursor returned as next_cursor by the preceding page", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "description": "Activates the paginated response envelope; values above 1000 are rejected", "maximum": 1000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Without cursor or limit the legacy response is a bare array. Supplying either pagination query returns an object containing items and, when another page exists, next_cursor.", "oneOf": [ { "items": { "additionalProperties": false, "properties": { "document": { "$ref": "#/components/schemas/DisplayDocument" }, "folder_id": { "format": "uuid", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "kind": { "type": "string" }, "lint": { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "enum": [ "note", "nudge" ], "type": "string" }, "widget_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "widget_id", "code", "message", "severity" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "schema_version": { "type": "string" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "id", "folder_id", "name", "kind", "schema_version", "tx_id", "document", "lint" ], "type": "object" }, "type": "array" }, { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "document": { "$ref": "#/components/schemas/DisplayDocument" }, "folder_id": { "format": "uuid", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "kind": { "type": "string" }, "lint": { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "enum": [ "note", "nudge" ], "type": "string" }, "widget_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "widget_id", "code", "message", "severity" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "schema_version": { "type": "string" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "id", "folder_id", "name", "kind", "schema_version", "tx_id", "document", "lint" ], "type": "object" }, "type": "array" }, "next_cursor": { "type": "string" } }, "required": [ "items" ], "type": "object" } ] } } }, "description": "Display documents; unreadable folders are silently absent. The response is a bare array unless cursor or limit activates keyset pagination." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid cursor or pagination limit above 1000" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List readable display documents", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" }, "post": { "operationId": "post_v1_displays", "parameters": [ { "in": "query", "name": "folder_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "description": "Replays the first successful response for the same authenticated principal, route, key, and request body", "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisplayDocument" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DisplayDocument" } }, "text/yaml": { "schema": { "$ref": "#/components/schemas/DisplayDocument" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "document": { "$ref": "#/components/schemas/DisplayDocument" }, "folder_id": { "format": "uuid", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "kind": { "type": "string" }, "lint": { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "enum": [ "note", "nudge" ], "type": "string" }, "widget_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "widget_id", "code", "message", "severity" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "schema_version": { "type": "string" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "id", "folder_id", "name", "kind", "schema_version", "tx_id", "document", "lint" ], "type": "object" } } }, "description": "Saved display and non-blocking lint rows", "headers": { "X-Ordinate-Idempotent-Replay": { "description": "Present with the literal value `true` when this response was replayed", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid display document; Invalid or oversized Idempotency-Key" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "display-author capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Display name conflict; Idempotency-Key was already used with a different request body" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Display document exceeds configured byte cap" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Save a new display document", "x-ordinate-capability": "display-author", "x-ordinate-scope": "handler-resolved target" } }, "/v1/displays/resolve": { "get": { "operationId": "get_v1_displays_resolve", "parameters": [ { "in": "query", "name": "asset", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "display", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "document": { "$ref": "#/components/schemas/DisplayDocument" }, "lint": { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "enum": [ "note", "nudge" ], "type": "string" }, "widget_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "widget_id", "code", "message", "severity" ], "type": "object" }, "type": "array" }, "schema_version": { "type": "string" }, "source": { "additionalProperties": true, "properties": { "kind": { "enum": [ "saved", "template", "ad-hoc" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } }, "required": [ "document", "schema_version", "source", "lint" ], "type": "object" } } }, "description": "Renderable document with hydrated selectors, origin, and lint" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unsupported display selector" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Asset, template, or display not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Resolve a saved or generated display for an asset", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" } }, "/v1/displays/time/navigator-context": { "post": { "operationId": "post_v1_displays_time_navigator_context", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "context": { "enum": [ "day", "week", "month", "six-months", "year" ], "type": "string" }, "main_end_ns": { "description": "Exact decimal i64 UTC nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" }, "main_start_ns": { "description": "Exact decimal i64 UTC nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" }, "timezone": { "oneOf": [ { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "automatic" ], "type": "string" } }, "required": [ "mode" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "enum": [ "explicit" ], "type": "string" }, "timezone": { "type": "string" } }, "required": [ "mode", "timezone" ], "type": "object" } ] } }, "required": [ "main_start_ns", "main_end_ns", "context", "timezone" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "context": { "type": "string" }, "end_ns": { "description": "Exact decimal i64 UTC nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" }, "main_end_ns": { "description": "Exact decimal i64 UTC nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" }, "main_start_ns": { "description": "Exact decimal i64 UTC nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" }, "start_ns": { "description": "Exact decimal i64 UTC nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" }, "timezone": { "type": "string" }, "timezone_fallback": { "type": "boolean" }, "timezone_source_asset": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } }, "required": [ "main_start_ns", "main_end_ns", "context", "start_ns", "end_ns", "timezone", "timezone_source_asset", "timezone_fallback" ], "type": "object" } } }, "description": "Main and context bounds in the resolved timezone" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bounds are noncanonical, unordered, or outside the calendar range" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Resolve a calendar-aware navigator context window", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" } }, "/v1/displays/time/resolve": { "post": { "operationId": "post_v1_displays_time_resolve", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "end": { "type": "string" }, "end_disambiguation": { "enum": [ "earlier", "later" ], "type": "string" }, "start": { "type": "string" }, "start_disambiguation": { "enum": [ "earlier", "later" ], "type": "string" }, "timezone": { "oneOf": [ { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "automatic" ], "type": "string" } }, "required": [ "mode" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "enum": [ "explicit" ], "type": "string" }, "timezone": { "type": "string" } }, "required": [ "mode", "timezone" ], "type": "object" } ] } }, "required": [ "start", "end", "timezone" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "end_expression": { "type": "string" }, "end_local": { "type": "string" }, "end_ns": { "description": "Exact decimal i64 UTC nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" }, "end_utc": { "type": "string" }, "live": { "type": "boolean" }, "start_expression": { "type": "string" }, "start_local": { "type": "string" }, "start_ns": { "description": "Exact decimal i64 UTC nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" }, "start_utc": { "type": "string" }, "timezone": { "type": "string" }, "timezone_fallback": { "type": "boolean" }, "timezone_source_asset": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } }, "required": [ "start_expression", "end_expression", "start_ns", "end_ns", "start_utc", "end_utc", "start_local", "end_local", "timezone", "timezone_source_asset", "timezone_fallback", "live" ], "type": "object" } } }, "description": "Resolved exact bounds and display timezone" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid timezone, syntax, range, or nonexistent local time" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Automatic timezone asset not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Ambiguous local time requires disambiguation" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Resolve display time expressions exactly", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" } }, "/v1/displays/{id}": { "get": { "operationId": "get_v1_displays_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "document": { "$ref": "#/components/schemas/DisplayDocument" }, "folder_id": { "format": "uuid", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "kind": { "type": "string" }, "lint": { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "enum": [ "note", "nudge" ], "type": "string" }, "widget_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "widget_id", "code", "message", "severity" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "schema_version": { "type": "string" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "id", "folder_id", "name", "kind", "schema_version", "tx_id", "document", "lint" ], "type": "object" } } }, "description": "Display document" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Display not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read a display document", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" }, "put": { "operationId": "put_v1_displays_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "expected_tx", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "in": "query", "name": "folder_id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisplayDocument" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DisplayDocument" } }, "text/yaml": { "schema": { "$ref": "#/components/schemas/DisplayDocument" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "document": { "$ref": "#/components/schemas/DisplayDocument" }, "folder_id": { "format": "uuid", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "kind": { "type": "string" }, "lint": { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "enum": [ "note", "nudge" ], "type": "string" }, "widget_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "widget_id", "code", "message", "severity" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "schema_version": { "type": "string" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "id", "folder_id", "name", "kind", "schema_version", "tx_id", "document", "lint" ], "type": "object" } } }, "description": "Updated display and lint rows" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "expected_tx is required or document is invalid" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "display-author capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Display not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Transaction or name conflict" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Display document exceeds configured byte cap" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Save a new version of a display document", "x-ordinate-capability": "display-author", "x-ordinate-scope": "handler-resolved target" } }, "/v1/displays/{id}/export": { "get": { "operationId": "get_v1_displays_by_id_export", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "format", "required": false, "schema": { "enum": [ "json", "yaml" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisplayDocument" } }, "application/yaml": { "schema": { "$ref": "#/components/schemas/DisplayDocument" } } }, "description": "Canonical JSON or YAML according to format" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Display not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Export a canonical display document", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" } }, "/v1/displays/{id}/lint": { "get": { "operationId": "get_v1_displays_by_id_lint", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "enum": [ "note", "nudge" ], "type": "string" }, "widget_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "widget_id", "code", "message", "severity" ], "type": "object" }, "type": "array" } } }, "description": "Non-blocking lint rows" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Display not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Lint a stored display document", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" } }, "/v1/episodes": { "post": { "operationId": "post_v1_episodes", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "asset_refs": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "role": { "type": "string" } }, "required": [ "asset_id", "role" ], "type": "object" }, "type": "array" }, "attributes": { "additionalProperties": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "type": "object" }, "end_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "origin": { "enum": [ "trigger", "api", "manual", "retroactive" ], "type": "string" }, "parent": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "template": { "format": "uuid", "type": "string" } }, "required": [ "template", "start_ns" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "flags": { "items": { "type": "string" }, "type": "array" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "origin": { "enum": [ "trigger", "api", "manual", "retroactive" ], "type": "string" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "id", "version", "name", "flags", "origin" ], "type": "object" } } }, "description": "Created episode identity and computed flags" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid episode, time span, template, roles, or attributes" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "episode-manage capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Episode or template not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Create an episode", "x-honest-oddity": "Overlap, grammar, nesting, and naming violations are stored successfully and reported in flags rather than rejected.", "x-ordinate-capability": "episode-manage", "x-ordinate-scope": "handler-resolved target" } }, "/v1/episodes/query": { "post": { "operationId": "post_v1_episodes_query", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "assets": { "additionalProperties": false, "properties": { "downstream_of": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "depth": { "oneOf": [ { "minimum": 0, "type": "integer" }, { "const": "*" } ] }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset_id", "depth" ], "type": "object" }, "ids": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "role": { "type": "string" }, "subtree": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" } }, "required": [ "asset_id" ], "type": "object" }, "upstream_of": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "depth": { "oneOf": [ { "minimum": 0, "type": "integer" }, { "const": "*" } ] }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset_id", "depth" ], "type": "object" } }, "required": [], "type": "object" }, "cursor": { "type": "string" }, "flags": { "items": { "type": "string" }, "type": "array" }, "include_voided": { "type": "boolean" }, "limit": { "format": "int64", "type": "integer" }, "overlaps": { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" }, "parent": { "format": "uuid", "type": "string" }, "state": { "items": { "enum": [ "open", "closed", "voided" ], "type": "string" }, "type": "array" }, "templates": { "items": { "type": "string" }, "type": "array" }, "where": { "type": "string" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "episodes": { "items": { "additionalProperties": false, "properties": { "asset_refs": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "role": { "type": "string" } }, "required": [ "asset_id", "role" ], "type": "object" }, "type": "array" }, "attributes": { "additionalProperties": { "additionalProperties": false, "properties": { "class": { "enum": [ "static", "captured", "manual" ], "type": "string" }, "provenance": { "anyOf": [ { "additionalProperties": false, "properties": { "computed_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "percent_good": { "type": "number" }, "window": { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" } }, "required": [ "window", "percent_good", "computed_at_ns" ], "type": "object" }, { "type": "null" } ] }, "provisional": { "description": "True values are stored provisional captures refreshed asynchronously by the episode engine; a GET does not recompute them at read time.", "type": "boolean" }, "quality": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "value": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" } }, "required": [ "class", "value", "unit", "quality", "provisional", "provenance" ], "type": "object" }, "type": "object" }, "children": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "created_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "end_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "flags": { "items": { "type": "string" }, "type": "array" }, "id": { "format": "uuid", "type": "string" }, "links": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "name": { "type": "string" }, "origin": { "enum": [ "trigger", "api", "manual", "retroactive" ], "type": "string" }, "parent": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "state": { "enum": [ "open", "closed", "voided" ], "type": "string" }, "template": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "id", "name", "version" ], "type": "object" }, "version": { "format": "int64", "type": "integer" }, "void": { "anyOf": [ { "additionalProperties": false, "properties": { "at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "by": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "reason", "at_ns", "by" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "id", "template", "name", "state", "start_ns", "end_ns", "parent", "asset_refs", "attributes", "flags", "origin", "void", "created_at_ns", "version" ], "type": "object" }, "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "episodes", "next_cursor" ], "type": "object" } } }, "description": "Filtered, keyset-paginated episodes" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Malformed cursor, template, filter, topology, or range" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Query episodes", "x-honest-oddity": "Voided episodes are hidden by default and are restored only when include_voided=true; direct GET by id still serves them.", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" } }, "/v1/episodes/templates": { "get": { "operationId": "get_v1_episodes_templates", "parameters": [ { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "templates": { "items": { "additionalProperties": false, "properties": { "attributes": { "items": { "additionalProperties": false, "properties": { "capture": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "class": { "enum": [ "static", "captured", "manual" ], "type": "string" }, "enum_set": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "quantity_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "class", "quantity_kind", "unit", "capture", "enum_set" ], "type": "object" }, "type": "array" }, "family": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "naming_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overlap": { "enum": [ "allowed", "exclusive" ], "type": "string" }, "permitted_children": { "items": { "type": "string" }, "type": "array" }, "reason": { "type": "string" }, "retro_edit_approval": { "enum": [ "none", "required" ], "type": "string" }, "roles": { "items": { "additionalProperties": false, "properties": { "cardinality": { "enum": [ "one", "many" ], "type": "string" }, "required": { "type": "boolean" }, "role": { "type": "string" } }, "required": [ "role", "required", "cardinality" ], "type": "object" }, "type": "array" }, "trigger": { "anyOf": [ { "additionalProperties": false, "properties": { "min_duration_ms": { "format": "int64", "type": "integer" }, "open_when": { "type": "string" } }, "required": [ "open_when", "min_duration_ms" ], "type": "object" }, { "type": "null" } ] }, "version": { "format": "int64", "type": "integer" } }, "required": [ "name", "family", "overlap", "retro_edit_approval", "id", "version" ], "type": "object" }, "type": "array" } }, "required": [ "templates" ], "type": "object" } } }, "description": "Templates valid at the requested time" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List episode templates", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" }, "post": { "operationId": "post_v1_episodes_templates", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attributes": { "items": { "additionalProperties": false, "properties": { "capture": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "class": { "enum": [ "static", "captured", "manual" ], "type": "string" }, "enum_set": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "quantity_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "class", "quantity_kind", "unit", "capture", "enum_set" ], "type": "object" }, "type": "array" }, "family": { "type": "string" }, "name": { "type": "string" }, "naming_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overlap": { "enum": [ "allowed", "exclusive" ], "type": "string" }, "permitted_children": { "items": { "type": "string" }, "type": "array" }, "reason": { "type": "string" }, "retro_edit_approval": { "enum": [ "none", "required" ], "type": "string" }, "roles": { "items": { "additionalProperties": false, "properties": { "cardinality": { "enum": [ "one", "many" ], "type": "string" }, "required": { "type": "boolean" }, "role": { "type": "string" } }, "required": [ "role", "required", "cardinality" ], "type": "object" }, "type": "array" }, "trigger": { "anyOf": [ { "additionalProperties": false, "properties": { "min_duration_ms": { "format": "int64", "type": "integer" }, "open_when": { "type": "string" } }, "required": [ "open_when", "min_duration_ms" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "name", "family", "overlap", "retro_edit_approval" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "id", "version" ], "type": "object" } } }, "description": "Created template identity" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid template, role, capture, or trigger" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "episode-manage capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Episode or template not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Create an episode template", "x-honest-oddity": "retro_edit_approval accepts only `none` in v1; `required` intentionally returns 400 until the approval pipeline exists.", "x-ordinate-capability": "episode-manage", "x-ordinate-scope": "held anywhere" } }, "/v1/episodes/templates/{id}": { "get": { "operationId": "get_v1_episodes_templates_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attributes": { "items": { "additionalProperties": false, "properties": { "capture": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "class": { "enum": [ "static", "captured", "manual" ], "type": "string" }, "enum_set": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "quantity_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "class", "quantity_kind", "unit", "capture", "enum_set" ], "type": "object" }, "type": "array" }, "family": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "naming_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overlap": { "enum": [ "allowed", "exclusive" ], "type": "string" }, "permitted_children": { "items": { "type": "string" }, "type": "array" }, "reason": { "type": "string" }, "retro_edit_approval": { "enum": [ "none", "required" ], "type": "string" }, "roles": { "items": { "additionalProperties": false, "properties": { "cardinality": { "enum": [ "one", "many" ], "type": "string" }, "required": { "type": "boolean" }, "role": { "type": "string" } }, "required": [ "role", "required", "cardinality" ], "type": "object" }, "type": "array" }, "trigger": { "anyOf": [ { "additionalProperties": false, "properties": { "min_duration_ms": { "format": "int64", "type": "integer" }, "open_when": { "type": "string" } }, "required": [ "open_when", "min_duration_ms" ], "type": "object" }, { "type": "null" } ] }, "version": { "format": "int64", "type": "integer" } }, "required": [ "name", "family", "overlap", "retro_edit_approval", "id", "version" ], "type": "object" } } }, "description": "Template valid at the requested time" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid template id" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Episode or template not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read an episode template", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" }, "put": { "operationId": "put_v1_episodes_templates_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attributes": { "items": { "additionalProperties": false, "properties": { "capture": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "class": { "enum": [ "static", "captured", "manual" ], "type": "string" }, "enum_set": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "quantity_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "class", "quantity_kind", "unit", "capture", "enum_set" ], "type": "object" }, "type": "array" }, "family": { "type": "string" }, "name": { "type": "string" }, "naming_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overlap": { "enum": [ "allowed", "exclusive" ], "type": "string" }, "permitted_children": { "items": { "type": "string" }, "type": "array" }, "reason": { "type": "string" }, "retro_edit_approval": { "enum": [ "none", "required" ], "type": "string" }, "roles": { "items": { "additionalProperties": false, "properties": { "cardinality": { "enum": [ "one", "many" ], "type": "string" }, "required": { "type": "boolean" }, "role": { "type": "string" } }, "required": [ "role", "required", "cardinality" ], "type": "object" }, "type": "array" }, "trigger": { "anyOf": [ { "additionalProperties": false, "properties": { "min_duration_ms": { "format": "int64", "type": "integer" }, "open_when": { "type": "string" } }, "required": [ "open_when", "min_duration_ms" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "name", "family", "overlap", "retro_edit_approval" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "version": { "format": "int64", "type": "integer" } }, "required": [ "version" ], "type": "object" } } }, "description": "New template version" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid template revision" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "episode-manage capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Episode or template not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Revise an episode template", "x-honest-oddity": "retro_edit_approval accepts only `none` in v1; `required` intentionally returns 400 until the approval pipeline exists.", "x-ordinate-capability": "episode-manage", "x-ordinate-scope": "held anywhere" } }, "/v1/episodes/traverse": { "post": { "operationId": "post_v1_episodes_traverse", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "depth": { "oneOf": [ { "minimum": 0, "type": "integer" }, { "const": "*" } ] }, "direction": { "enum": [ "upstream", "downstream" ], "type": "string" }, "include_voided": { "type": "boolean" }, "start": { "format": "uuid", "type": "string" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "start", "direction", "depth" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "episodes": { "items": { "additionalProperties": true, "properties": {}, "required": [], "type": "object" }, "type": "array" }, "links": { "items": { "additionalProperties": false, "properties": { "attributes": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "created_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "direction": { "enum": [ "out", "in" ], "type": "string" }, "from_episode": { "format": "uuid", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "link_type": { "type": "string" }, "to_episode": { "format": "uuid", "type": "string" } }, "required": [ "id", "from_episode", "to_episode", "link_type", "attributes", "created_at_ns" ], "type": "object" }, "type": "array" }, "warnings": { "items": { "enum": [ "cycle-detected", "result-cap-exceeded" ], "type": "string" }, "type": "array" } }, "required": [ "episodes", "links", "warnings" ], "type": "object" } } }, "description": "Reachable readable episodes and non-dangling links" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Malformed traversal, depth, or link type" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Start episode not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Traverse episode genealogy", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" } }, "/v1/episodes/{id}": { "get": { "operationId": "get_v1_episodes_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "include_children", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "include_links", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "asset_refs": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "role": { "type": "string" } }, "required": [ "asset_id", "role" ], "type": "object" }, "type": "array" }, "attributes": { "additionalProperties": { "additionalProperties": false, "properties": { "class": { "enum": [ "static", "captured", "manual" ], "type": "string" }, "provenance": { "anyOf": [ { "additionalProperties": false, "properties": { "computed_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "percent_good": { "type": "number" }, "window": { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns" ], "type": "object" } }, "required": [ "window", "percent_good", "computed_at_ns" ], "type": "object" }, { "type": "null" } ] }, "provisional": { "description": "True values are stored provisional captures refreshed asynchronously by the episode engine; a GET does not recompute them at read time.", "type": "boolean" }, "quality": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "value": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" } }, "required": [ "class", "value", "unit", "quality", "provisional", "provenance" ], "type": "object" }, "type": "object" }, "children": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "created_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "end_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "flags": { "items": { "type": "string" }, "type": "array" }, "id": { "format": "uuid", "type": "string" }, "links": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "name": { "type": "string" }, "origin": { "enum": [ "trigger", "api", "manual", "retroactive" ], "type": "string" }, "parent": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "state": { "enum": [ "open", "closed", "voided" ], "type": "string" }, "template": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "id", "name", "version" ], "type": "object" }, "version": { "format": "int64", "type": "integer" }, "void": { "anyOf": [ { "additionalProperties": false, "properties": { "at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "by": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "reason", "at_ns", "by" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "id", "template", "name", "state", "start_ns", "end_ns", "parent", "asset_refs", "attributes", "flags", "origin", "void", "created_at_ns", "version" ], "type": "object" } } }, "description": "Current episode record" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid episode id" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Episode or template not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read an episode", "x-honest-oddity": "A voided episode still returns 200 with its full record. Provisional captured values are stored and refreshed on the engine tick, not recomputed by this read.", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" }, "put": { "operationId": "put_v1_episodes_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "asset_refs": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "role": { "type": "string" } }, "required": [ "asset_id", "role" ], "type": "object" }, "type": "array" }, "attributes": { "additionalProperties": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "type": "object" }, "end_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "reason": { "type": "string" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "flags": { "items": { "type": "string" }, "type": "array" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "version", "flags" ], "type": "object" } } }, "description": "New episode version and computed flags" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid edit or attempted immutable template/parent change" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "episode-manage capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Episode or template not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Edit an episode", "x-honest-oddity": "Overlap, grammar, nesting, and naming violations are stored successfully and reported in flags rather than rejected.", "x-ordinate-capability": "episode-manage", "x-ordinate-scope": "handler-resolved target" } }, "/v1/episodes/{id}/close": { "post": { "operationId": "post_v1_episodes_by_id_close", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "reason": { "type": "string" } }, "required": [ "end_ns" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "version": { "format": "int64", "type": "integer" } }, "required": [ "version" ], "type": "object" } } }, "description": "New closed episode version" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid close time" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "episode-manage capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Episode or template not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Close an open episode", "x-ordinate-capability": "episode-manage", "x-ordinate-scope": "handler-resolved target" } }, "/v1/episodes/{id}/links": { "get": { "operationId": "get_v1_episodes_by_id_links", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "links": { "items": { "additionalProperties": false, "properties": { "attributes": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "created_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "direction": { "enum": [ "out", "in" ], "type": "string" }, "from_episode": { "format": "uuid", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "link_type": { "type": "string" }, "to_episode": { "format": "uuid", "type": "string" } }, "required": [ "id", "from_episode", "to_episode", "link_type", "attributes", "created_at_ns" ], "type": "object" }, "type": "array" } }, "required": [ "links" ], "type": "object" } } }, "description": "Incoming and outgoing links" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid episode id" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Episode or template not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List episode genealogy links", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" }, "post": { "operationId": "post_v1_episodes_by_id_links", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attributes": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "link_type": { "type": "string" }, "to": { "format": "uuid", "type": "string" } }, "required": [ "to", "link_type" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" } } }, "description": "Created link identity" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid link or unregistered link type" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "episode-manage capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Episode or template not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Create an episode genealogy link", "x-ordinate-capability": "episode-manage", "x-ordinate-scope": "handler-resolved target" } }, "/v1/episodes/{id}/void": { "post": { "operationId": "post_v1_episodes_by_id_void", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "reason": { "type": "string" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "version": { "format": "int64", "type": "integer" } }, "required": [ "version" ], "type": "object" } } }, "description": "New voided episode version" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid void request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "episode-manage capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Episode or template not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Void an episode", "x-ordinate-capability": "episode-manage", "x-ordinate-scope": "handler-resolved target" } }, "/v1/healthz": { "get": { "operationId": "get_v1_healthz", "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "The literal text `ok`" } }, "security": [], "summary": "Report process liveness", "x-ordinate-capability": "anonymous", "x-ordinate-scope": "none" } }, "/v1/jobs": { "get": { "operationId": "get_v1_jobs", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": false, "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "finished_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "job_id": { "format": "int64", "type": "integer" }, "kind": { "type": "string" }, "params": { "type": "string" }, "progress": { "type": "string" }, "started_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "state": { "type": "string" }, "updated_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "job_id", "kind", "state", "params", "progress", "started_ns", "updated_ns", "finished_ns", "error" ], "type": "object" }, "type": "array" } } }, "description": "Job ledger" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" } }, "summary": "List storage jobs", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" } }, "/v1/jobs/retention-backfill": { "post": { "operationId": "post_v1_jobs_retention_backfill", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "description": "Replays the first successful response for the same authenticated principal, route, key, and request body", "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "confirm": { "type": "boolean" }, "policy_version": { "format": "int64", "type": "integer" }, "series_uuid": { "format": "uuid", "type": "string" } }, "required": [ "series_uuid", "policy_version" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "job_id": { "format": "int64", "type": "integer" } }, "required": [ "job_id" ], "type": "object" } } }, "description": "Backfill accepted", "headers": { "X-Ordinate-Idempotent-Replay": { "description": "Present with the literal value `true` when this response was replayed", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "Explicit confirm:true or a valid series UUID is required; Invalid or oversized Idempotency-Key" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Admin capability is not granted at the staging root" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "A matching backfill is already in flight; Idempotency-Key was already used with a different request body" } }, "summary": "Enqueue a confirmed retention backfill", "x-ordinate-capability": "admin", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/assets": { "post": { "operationId": "post_v1_model_assets", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "parent": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" }, "template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "effective_timezone": { "type": "string" }, "name": { "type": "string" }, "parent_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retired": { "type": "boolean" }, "template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone_source_asset": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "asset_id", "parent_id", "name", "template_id", "retired", "tx_id", "path", "timezone", "effective_timezone", "timezone_source_asset" ], "type": "object" } } }, "description": "Created asset projection" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid asset" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Name or transaction conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Create an asset", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/assets/{uuid}": { "get": { "operationId": "get_v1_model_assets_by_uuid", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "effective_timezone": { "type": "string" }, "name": { "type": "string" }, "parent_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retired": { "type": "boolean" }, "template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone_source_asset": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "asset_id", "parent_id", "name", "template_id", "retired", "tx_id", "path", "timezone", "effective_timezone", "timezone_source_asset" ], "type": "object" } } }, "description": "Asset with computed path and inherited timezone" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid UUID" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Asset not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read an asset projection", "x-ordinate-capability": "read", "x-ordinate-scope": "asset path parameter `uuid`" }, "patch": { "operationId": "patch_v1_model_assets_by_uuid", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expected_tx": { "format": "int64", "type": "integer" }, "move": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" }, "rename": { "type": "string" }, "retire": { "type": "boolean" }, "unretire": { "type": "boolean" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "effective_timezone": { "type": "string" }, "name": { "type": "string" }, "parent_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retired": { "type": "boolean" }, "template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone_source_asset": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "asset_id", "parent_id", "name", "template_id", "retired", "tx_id", "path", "timezone", "effective_timezone", "timezone_source_asset" ], "type": "object" } } }, "description": "Updated asset projection" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid patch" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Asset not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Name or transaction conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Rename, move, retire, or unretire an asset", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/assets/{uuid}/instantiate": { "post": { "operationId": "post_v1_model_assets_by_uuid_instantiate", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "reason": { "type": "string" }, "template_id": { "format": "uuid", "type": "string" } }, "required": [ "template_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "attr_def_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "attribute_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "overrides": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "retired": { "type": "boolean" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "attribute_id", "asset_id", "attr_def_id", "name", "overrides", "retired", "tx_id" ], "type": "object" }, "type": "array" } } }, "description": "Created attribute instances" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Asset or template not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Instantiation conflicts with current model" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Instantiate a template beneath an asset", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/assets/{uuid}/links": { "get": { "operationId": "get_v1_model_assets_by_uuid_links", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "from", "to" ], "type": "string" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, { "in": "query", "name": "include_retired", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "links": { "items": { "additionalProperties": false, "properties": { "from_asset": { "format": "uuid", "type": "string" }, "gating_expression": { "type": "string" }, "link_id": { "format": "uuid", "type": "string" }, "link_type_id": { "format": "uuid", "type": "string" }, "retired": { "type": "boolean" }, "to_asset": { "format": "uuid", "type": "string" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "link_id", "from_asset", "to_asset", "link_type_id", "gating_expression", "retired", "tx_id", "valid_from_ns" ], "type": "object" }, "type": "array" } }, "required": [ "links" ], "type": "object" } } }, "description": "Asset links" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List links involving an asset", "x-ordinate-capability": "read", "x-ordinate-scope": "asset path parameter `uuid`" } }, "/v1/model/assets/{uuid}/properties": { "get": { "operationId": "get_v1_model_assets_by_uuid_properties", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "effective", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "properties": { "items": { "oneOf": [ { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "key": { "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "value": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" } }, "required": [ "property_id", "asset_id", "key", "value", "tx_id", "valid_from_ns" ], "type": "object" }, { "additionalProperties": false, "properties": { "key": { "type": "string" }, "source_asset": { "format": "uuid", "type": "string" }, "value": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" } }, "required": [ "key", "value", "source_asset" ], "type": "object" } ] }, "type": "array" } }, "required": [ "properties" ], "type": "object" } } }, "description": "Own rows or effective values depending on effective=true" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List own or effective asset properties", "x-ordinate-capability": "read", "x-ordinate-scope": "asset path parameter `uuid`" } }, "/v1/model/assets/{uuid}/properties/{key}": { "delete": { "operationId": "delete_v1_model_assets_by_uuid_properties_by_key", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expected_tx": { "format": "int64", "type": "integer" }, "reason": { "type": "string" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "cleared_at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "key": { "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "property_id", "asset_id", "key", "tx_id", "cleared_at_ns" ], "type": "object" } } }, "description": "Cleared property receipt" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Property not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Transaction conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Clear an asset property override", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" }, "put": { "operationId": "put_v1_model_assets_by_uuid_properties_by_key", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expected_tx": { "format": "int64", "type": "integer" }, "reason": { "type": "string" }, "value": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" } }, "required": [ "value" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "key": { "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "value": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" } }, "required": [ "property_id", "asset_id", "key", "value", "tx_id", "valid_from_ns" ], "type": "object" } } }, "description": "Stored property" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unknown or invalid property" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Transaction conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Set an asset property", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/attributes": { "post": { "operationId": "post_v1_model_attributes", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "attr_def_id": { "format": "uuid", "type": "string" }, "def": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "name": { "type": "string" }, "overrides": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "reason": { "type": "string" } }, "required": [ "asset", "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "attr_def_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "attribute_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "overrides": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "retired": { "type": "boolean" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "attribute_id", "asset_id", "attr_def_id", "name", "overrides", "retired", "tx_id" ], "type": "object" } } }, "description": "Created attribute" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid attribute" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Asset or definition not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Attribute name conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Create an attribute instance", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/attributes/{uuid}": { "get": { "operationId": "get_v1_model_attributes_by_uuid", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "attr_def_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "attribute_id": { "format": "uuid", "type": "string" }, "continuity_class": { "enum": [ "continuous", "stepped", "event" ], "type": "string" }, "display_unit_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "entry_cadence": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "enum_set_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "lifecycle_policy": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "limit_traits": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "name": { "type": "string" }, "overridden_fields": { "items": { "type": "string" }, "type": "array" }, "quantity_kind_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "retired": { "type": "boolean" }, "writer_class": { "enum": [ "collector", "calculated", "manual" ], "type": "string" } }, "required": [ "attribute_id", "asset_id", "name", "attr_def_id", "quantity_kind_id", "display_unit_id", "continuity_class", "writer_class", "enum_set_id", "limit_traits", "lifecycle_policy", "entry_cadence", "retired", "overridden_fields" ], "type": "object" } } }, "description": "Effective attribute" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Attribute not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read an effective attribute", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" }, "patch": { "operationId": "patch_v1_model_attributes_by_uuid", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "reason": { "type": "string" }, "retire": { "type": "boolean" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "attr_def_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "attribute_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "overrides": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "retired": { "type": "boolean" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "attribute_id", "asset_id", "attr_def_id", "name", "overrides", "retired", "tx_id" ], "type": "object" } } }, "description": "Current or retired attribute" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Attribute not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Retire an attribute instance", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/attributes/{uuid}/bindings": { "get": { "operationId": "get_v1_model_attributes_by_uuid_bindings", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "segments": { "items": { "additionalProperties": false, "properties": { "binding_id": { "format": "uuid", "type": "string" }, "effective_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "effective_to_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "series_uuid": { "format": "uuid", "type": "string" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "binding_id", "series_uuid", "effective_from_ns", "effective_to_ns", "tx_id" ], "type": "object" }, "type": "array" } }, "required": [ "attribute_id", "segments" ], "type": "object" } } }, "description": "Binding timeline" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read an attribute binding timeline", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/bindings": { "post": { "operationId": "post_v1_model_bindings", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "additionalProperties": false, "properties": { "attribute": { "format": "uuid", "type": "string" }, "effective_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "op": { "enum": [ "bind" ], "type": "string" }, "reason": { "type": "string" }, "series": { "format": "uuid", "type": "string" } }, "required": [ "op", "attribute", "series" ], "type": "object" }, { "additionalProperties": false, "properties": { "at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "attribute": { "format": "uuid", "type": "string" }, "new_series": { "format": "uuid", "type": "string" }, "op": { "enum": [ "rebind" ], "type": "string" }, "reason": { "type": "string" } }, "required": [ "op", "attribute", "new_series", "at_ns" ], "type": "object" }, { "additionalProperties": false, "properties": { "at_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "attribute": { "format": "uuid", "type": "string" }, "op": { "enum": [ "unbind" ], "type": "string" }, "reason": { "type": "string" } }, "required": [ "op", "attribute", "at_ns" ], "type": "object" }, { "additionalProperties": false, "properties": { "op": { "enum": [ "splice-revert" ], "type": "string" }, "reason": { "type": "string" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "op", "tx_id" ], "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "tx_id" ], "type": "object" } } }, "description": "Binding transaction" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid or inapplicable binding operation" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Binding target not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Binding overlap, conflict, or superseded splice" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Bind, rebind, unbind, or splice-revert a series", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/calc/rules": { "get": { "operationId": "get_v1_model_calc_rules", "parameters": [ { "in": "query", "name": "template_id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "asset_id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": false, "properties": { "declared_inferred": { "type": "boolean" }, "expression": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "provisional": { "enum": [ "block", "allow" ], "type": "string" }, "reason": { "type": "string" }, "retired": { "type": "boolean" }, "rule_id": { "format": "uuid", "type": "string" }, "scope": { "oneOf": [ { "additionalProperties": false, "properties": { "output_attr_def_id": { "format": "uuid", "type": "string" }, "template_id": { "format": "uuid", "type": "string" } }, "required": [ "template_id", "output_attr_def_id" ], "type": "object" }, { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "output_attribute_id": { "format": "uuid", "type": "string" } }, "required": [ "asset_id", "output_attribute_id" ], "type": "object" } ] }, "tier": { "enum": [ "expression", "external" ], "type": "string" }, "trigger": { "oneOf": [ { "additionalProperties": false, "properties": { "debounce_ms": { "anyOf": [ { "format": "int64", "type": "integer" }, { "type": "null" } ] }, "kind": { "enum": [ "event" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "align": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "interval_ns": { "format": "int64", "type": "integer" }, "kind": { "enum": [ "periodic" ], "type": "string" } }, "required": [ "kind", "interval_ns", "align" ], "type": "object" }, { "additionalProperties": false, "properties": { "edge": { "enum": [ "rising", "falling", "both" ], "type": "string" }, "expr": { "type": "string" }, "kind": { "enum": [ "condition" ], "type": "string" } }, "required": [ "kind", "expr", "edge" ], "type": "object" } ] }, "tx_id": { "format": "int64", "type": "integer" }, "unit_check": { "enum": [ "strict", "unchecked" ], "type": "string" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "version": { "format": "int64", "type": "integer" }, "when": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "scope", "tier", "trigger", "unit_check", "provisional", "rule_id", "version", "retired", "tx_id", "valid_from_ns" ], "type": "object" }, "type": "array" } } }, "description": "Calculation rules" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List calculation rules", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" }, "post": { "operationId": "post_v1_model_calc_rules", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "declared_inferred": { "type": "boolean" }, "expression": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "provisional": { "enum": [ "block", "allow" ], "type": "string" }, "reason": { "type": "string" }, "scope": { "oneOf": [ { "additionalProperties": false, "properties": { "output_attr_def_id": { "format": "uuid", "type": "string" }, "template_id": { "format": "uuid", "type": "string" } }, "required": [ "template_id", "output_attr_def_id" ], "type": "object" }, { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "output_attribute_id": { "format": "uuid", "type": "string" } }, "required": [ "asset_id", "output_attribute_id" ], "type": "object" } ] }, "tier": { "enum": [ "expression", "external" ], "type": "string" }, "trigger": { "oneOf": [ { "additionalProperties": false, "properties": { "debounce_ms": { "anyOf": [ { "format": "int64", "type": "integer" }, { "type": "null" } ] }, "kind": { "enum": [ "event" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "align": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "interval_ns": { "format": "int64", "type": "integer" }, "kind": { "enum": [ "periodic" ], "type": "string" } }, "required": [ "kind", "interval_ns", "align" ], "type": "object" }, { "additionalProperties": false, "properties": { "edge": { "enum": [ "rising", "falling", "both" ], "type": "string" }, "expr": { "type": "string" }, "kind": { "enum": [ "condition" ], "type": "string" } }, "required": [ "kind", "expr", "edge" ], "type": "object" } ] }, "unit_check": { "enum": [ "strict", "unchecked" ], "type": "string" }, "when": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "scope", "tier", "trigger", "unit_check", "provisional" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "rule_id": { "format": "uuid", "type": "string" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "rule_id", "version" ], "type": "object" } } }, "description": "Created rule identity and version" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Parse, dimension, reference, cycle, kind, or validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "calc-author capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Create a calculation rule", "x-ordinate-capability": "calc-author", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/calc/rules/{id}": { "get": { "operationId": "get_v1_model_calc_rules_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "declared_inferred": { "type": "boolean" }, "expression": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "provisional": { "enum": [ "block", "allow" ], "type": "string" }, "reason": { "type": "string" }, "retired": { "type": "boolean" }, "rule_id": { "format": "uuid", "type": "string" }, "scope": { "oneOf": [ { "additionalProperties": false, "properties": { "output_attr_def_id": { "format": "uuid", "type": "string" }, "template_id": { "format": "uuid", "type": "string" } }, "required": [ "template_id", "output_attr_def_id" ], "type": "object" }, { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "output_attribute_id": { "format": "uuid", "type": "string" } }, "required": [ "asset_id", "output_attribute_id" ], "type": "object" } ] }, "tier": { "enum": [ "expression", "external" ], "type": "string" }, "trigger": { "oneOf": [ { "additionalProperties": false, "properties": { "debounce_ms": { "anyOf": [ { "format": "int64", "type": "integer" }, { "type": "null" } ] }, "kind": { "enum": [ "event" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "align": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "interval_ns": { "format": "int64", "type": "integer" }, "kind": { "enum": [ "periodic" ], "type": "string" } }, "required": [ "kind", "interval_ns", "align" ], "type": "object" }, { "additionalProperties": false, "properties": { "edge": { "enum": [ "rising", "falling", "both" ], "type": "string" }, "expr": { "type": "string" }, "kind": { "enum": [ "condition" ], "type": "string" } }, "required": [ "kind", "expr", "edge" ], "type": "object" } ] }, "tx_id": { "format": "int64", "type": "integer" }, "unit_check": { "enum": [ "strict", "unchecked" ], "type": "string" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "version": { "format": "int64", "type": "integer" }, "when": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "scope", "tier", "trigger", "unit_check", "provisional", "rule_id", "version", "retired", "tx_id", "valid_from_ns" ], "type": "object" } } }, "description": "Calculation rule" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rule not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read a calculation rule", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" }, "put": { "operationId": "put_v1_model_calc_rules_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "recompute", "required": true, "schema": { "enum": [ "history", "from-now" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "declared_inferred": { "type": "boolean" }, "expression": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "provisional": { "enum": [ "block", "allow" ], "type": "string" }, "reason": { "type": "string" }, "scope": { "oneOf": [ { "additionalProperties": false, "properties": { "output_attr_def_id": { "format": "uuid", "type": "string" }, "template_id": { "format": "uuid", "type": "string" } }, "required": [ "template_id", "output_attr_def_id" ], "type": "object" }, { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "output_attribute_id": { "format": "uuid", "type": "string" } }, "required": [ "asset_id", "output_attribute_id" ], "type": "object" } ] }, "tier": { "enum": [ "expression", "external" ], "type": "string" }, "trigger": { "oneOf": [ { "additionalProperties": false, "properties": { "debounce_ms": { "anyOf": [ { "format": "int64", "type": "integer" }, { "type": "null" } ] }, "kind": { "enum": [ "event" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "align": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "interval_ns": { "format": "int64", "type": "integer" }, "kind": { "enum": [ "periodic" ], "type": "string" } }, "required": [ "kind", "interval_ns", "align" ], "type": "object" }, { "additionalProperties": false, "properties": { "edge": { "enum": [ "rising", "falling", "both" ], "type": "string" }, "expr": { "type": "string" }, "kind": { "enum": [ "condition" ], "type": "string" } }, "required": [ "kind", "expr", "edge" ], "type": "object" } ] }, "unit_check": { "enum": [ "strict", "unchecked" ], "type": "string" }, "when": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "scope", "tier", "trigger", "unit_check", "provisional" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "rule_id": { "format": "uuid", "type": "string" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "rule_id", "version" ], "type": "object" } } }, "description": "Updated rule identity and version" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing recompute or invalid rule" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "calc-author capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rule not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Create a new calculation rule version", "x-ordinate-capability": "calc-author", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/calc/rules/{id}/retire": { "post": { "operationId": "post_v1_model_calc_rules_by_id_retire", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "retired": { "type": "boolean" }, "rule_id": { "format": "uuid", "type": "string" } }, "required": [ "rule_id", "retired" ], "type": "object" } } }, "description": "Retirement receipt" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "calc-author capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rule not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Retire a calculation rule", "x-ordinate-capability": "calc-author", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/calc/rules/{id}/versions": { "get": { "operationId": "get_v1_model_calc_rules_by_id_versions", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": false, "properties": { "declared_inferred": { "type": "boolean" }, "expression": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "provisional": { "enum": [ "block", "allow" ], "type": "string" }, "reason": { "type": "string" }, "retired": { "type": "boolean" }, "rule_id": { "format": "uuid", "type": "string" }, "scope": { "oneOf": [ { "additionalProperties": false, "properties": { "output_attr_def_id": { "format": "uuid", "type": "string" }, "template_id": { "format": "uuid", "type": "string" } }, "required": [ "template_id", "output_attr_def_id" ], "type": "object" }, { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "output_attribute_id": { "format": "uuid", "type": "string" } }, "required": [ "asset_id", "output_attribute_id" ], "type": "object" } ] }, "tier": { "enum": [ "expression", "external" ], "type": "string" }, "trigger": { "oneOf": [ { "additionalProperties": false, "properties": { "debounce_ms": { "anyOf": [ { "format": "int64", "type": "integer" }, { "type": "null" } ] }, "kind": { "enum": [ "event" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, { "additionalProperties": false, "properties": { "align": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "interval_ns": { "format": "int64", "type": "integer" }, "kind": { "enum": [ "periodic" ], "type": "string" } }, "required": [ "kind", "interval_ns", "align" ], "type": "object" }, { "additionalProperties": false, "properties": { "edge": { "enum": [ "rising", "falling", "both" ], "type": "string" }, "expr": { "type": "string" }, "kind": { "enum": [ "condition" ], "type": "string" } }, "required": [ "kind", "expr", "edge" ], "type": "object" } ] }, "tx_id": { "format": "int64", "type": "integer" }, "unit_check": { "enum": [ "strict", "unchecked" ], "type": "string" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "version": { "format": "int64", "type": "integer" }, "when": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "scope", "tier", "trigger", "unit_check", "provisional", "rule_id", "version", "retired", "tx_id", "valid_from_ns" ], "type": "object" }, "type": "array" } } }, "description": "Rule versions in ascending order" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rule not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List calculation rule versions", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/events": { "get": { "operationId": "get_v1_model_events", "parameters": [ { "in": "query", "name": "since_tx", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": false, "properties": { "committed_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "events": { "items": { "additionalProperties": false, "properties": { "action": { "type": "string" }, "details": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "entity_id": { "format": "uuid", "type": "string" }, "entity_kind": { "type": "string" } }, "required": [ "entity_kind", "entity_id", "action", "details" ], "type": "object" }, "type": "array" }, "principal": { "type": "string" }, "reason": { "type": "string" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "tx_id", "committed_ns", "principal", "reason", "events" ], "type": "object" }, "type": "array" } } }, "description": "Transactions in ascending order with nested events" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read the model transaction event feed", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" } }, "/v1/model/events/subscribe": { "post": { "operationId": "post_v1_model_events_subscribe", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "assets": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "kinds": { "items": { "type": "string" }, "type": "array" }, "since_tx": { "format": "int64", "type": "integer" }, "templates": { "items": { "format": "uuid", "type": "string" }, "type": "array" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } } }, "description": "SSE events named by entity_kind with tx_id resume ids" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Concurrent model-event subscriber cap reached" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Subscribe to permission-filtered model events", "x-ordinate-capability": "read", "x-ordinate-scope": "handler-resolved target", "x-streaming": { "authorization": "live snapshot rechecked per delivered event", "event_shape": { "additionalProperties": false, "properties": { "action": { "type": "string" }, "committed_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "details": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "entity_id": { "format": "uuid", "type": "string" }, "entity_kind": { "type": "string" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "tx_id", "committed_ns", "entity_kind", "entity_id", "action", "details" ], "type": "object" }, "poll_interval_ms": 500, "resume": "Last-Event-ID header, then since_tx body field", "transport": "sse" } } }, "/v1/model/healthz": { "get": { "operationId": "get_v1_model_healthz", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "migrations": { "format": "int64", "type": "integer" }, "model": { "enum": [ "ok" ], "type": "string" } }, "required": [ "model", "migrations" ], "type": "object" } } }, "description": "Model store is reachable and migrated" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured" } }, "security": [], "summary": "Report model database readiness", "x-ordinate-capability": "anonymous", "x-ordinate-scope": "none" } }, "/v1/model/jobs": { "get": { "operationId": "get_v1_model_jobs", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": false, "properties": { "committed_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "created_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "job_id": { "format": "int64", "type": "integer" }, "kind": { "type": "string" }, "params": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "preview": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "principal": { "type": "string" }, "state": { "enum": [ "preview", "committed", "failed" ], "type": "string" } }, "required": [ "job_id", "kind", "state", "params", "preview", "created_ns", "committed_ns", "principal", "error" ], "type": "object" }, "type": "array" } } }, "description": "Model jobs newest first" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List model jobs", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" }, "post": { "operationId": "post_v1_model_jobs", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "description": "Replays the first successful response for the same authenticated principal, route, key, and request body", "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "kind": { "type": "string" }, "params": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" } }, "required": [ "kind" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "committed_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "created_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "job_id": { "format": "int64", "type": "integer" }, "kind": { "type": "string" }, "params": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "preview": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "principal": { "type": "string" }, "state": { "enum": [ "preview", "committed", "failed" ], "type": "string" } }, "required": [ "job_id", "kind", "state", "params", "preview", "created_ns", "committed_ns", "principal", "error" ], "type": "object" } } }, "description": "Stored preview job", "headers": { "X-Ordinate-Idempotent-Replay": { "description": "Present with the literal value `true` when this response was replayed", "schema": { "enum": [ "true" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unsupported or invalid job; Invalid or oversized Idempotency-Key" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Idempotency-Key was already used with a different request body" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Create and preview a model job", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/jobs/{id}": { "get": { "operationId": "get_v1_model_jobs_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "committed_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "created_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "job_id": { "format": "int64", "type": "integer" }, "kind": { "type": "string" }, "params": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "preview": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "principal": { "type": "string" }, "state": { "enum": [ "preview", "committed", "failed" ], "type": "string" } }, "required": [ "job_id", "kind", "state", "params", "preview", "created_ns", "committed_ns", "principal", "error" ], "type": "object" } } }, "description": "Model job" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Job not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read a model job", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" } }, "/v1/model/jobs/{id}/commit": { "post": { "operationId": "post_v1_model_jobs_by_id_commit", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "committed_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "created_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "job_id": { "format": "int64", "type": "integer" }, "kind": { "type": "string" }, "params": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "preview": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "principal": { "type": "string" }, "state": { "enum": [ "preview", "committed", "failed" ], "type": "string" } }, "required": [ "job_id", "kind", "state", "params", "preview", "created_ns", "committed_ns", "principal", "error" ], "type": "object" } } }, "description": "Committed job receipt" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Job is not in preview state" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Job not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model changed since preview" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Commit a previewed model job", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/links": { "post": { "operationId": "post_v1_model_links", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "from_asset": { "format": "uuid", "type": "string" }, "gating_expression": { "type": "string" }, "link_type_id": { "format": "uuid", "type": "string" }, "reason": { "type": "string" }, "to_asset": { "format": "uuid", "type": "string" } }, "required": [ "from_asset", "to_asset", "link_type_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "from_asset": { "format": "uuid", "type": "string" }, "gating_expression": { "type": "string" }, "link_id": { "format": "uuid", "type": "string" }, "link_type_id": { "format": "uuid", "type": "string" }, "retired": { "type": "boolean" }, "to_asset": { "format": "uuid", "type": "string" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "link_id", "from_asset", "to_asset", "link_type_id", "gating_expression", "retired", "tx_id", "valid_from_ns" ], "type": "object" } } }, "description": "Created link" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid or self link" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Duplicate link" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Create an asset link", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/links/{uuid}": { "patch": { "operationId": "patch_v1_model_links_by_uuid", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expected_tx": { "format": "int64", "type": "integer" }, "reason": { "type": "string" }, "retired": { "type": "boolean" } }, "required": [ "retired" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "from_asset": { "format": "uuid", "type": "string" }, "gating_expression": { "type": "string" }, "link_id": { "format": "uuid", "type": "string" }, "link_type_id": { "format": "uuid", "type": "string" }, "retired": { "type": "boolean" }, "to_asset": { "format": "uuid", "type": "string" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "link_id", "from_asset", "to_asset", "link_type_id", "gating_expression", "retired", "tx_id", "valid_from_ns" ], "type": "object" } } }, "description": "Updated link" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Link not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Transaction conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Retire or restore an asset link", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/lints": { "get": { "operationId": "get_v1_model_lints", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "created_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "details": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "kind": { "type": "string" }, "lint_id": { "format": "uuid", "type": "string" } }, "required": [], "type": "object" }, "type": "array" } } }, "description": "Open lint rows" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List open model governance lints", "x-honest-oddity": "Structural listing is authenticated but currently coarse any-Read", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" } }, "/v1/model/registries/{kind}": { "get": { "operationId": "get_v1_model_registries_by_kind", "parameters": [ { "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "enum-concepts", "enum-sets", "quantity-kinds", "units", "link-types", "annotation-tags", "episode-roles" ], "type": "string" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "entries": { "items": { "additionalProperties": true, "properties": { "canonical_unit_id": { "format": "uuid", "type": "string" }, "encoding": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "id": { "format": "uuid", "type": "string" }, "integrates_to": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "kind_id": { "format": "uuid", "type": "string" }, "members": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "name": { "type": "string" }, "rationale": { "type": "string" }, "symbol": { "type": "string" }, "system": { "type": "boolean" }, "to_canonical_factor": { "format": "double", "type": "number" }, "to_canonical_offset": { "format": "double", "type": "number" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "valid_to_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" } }, "required": [ "entries" ], "type": "object" } } }, "description": "Registry entries with a generic id plus kind-specific fields" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "description": "Unknown registry kind" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List a governed registry", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" } }, "/v1/model/registries/{kind}/entries": { "post": { "operationId": "post_v1_model_registries_by_kind_entries", "parameters": [ { "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "enum-concepts", "enum-sets", "quantity-kinds", "units", "link-types", "annotation-tags", "episode-roles" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "canonical_unit_name": { "type": "string" }, "canonical_unit_symbol": { "type": "string" }, "encoding": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "integrates_to": { "format": "uuid", "type": "string" }, "kind_id": { "format": "uuid", "type": "string" }, "members": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "name": { "type": "string" }, "override": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "rationale": { "type": "string" }, "symbol": { "type": "string" }, "to_canonical_factor": { "format": "double", "type": "number" }, "to_canonical_offset": { "format": "double", "type": "number" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "canonical_unit_id": { "format": "uuid", "type": "string" }, "encoding": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "id": { "format": "uuid", "type": "string" }, "integrates_to": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "kind_id": { "format": "uuid", "type": "string" }, "members": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "name": { "type": "string" }, "rationale": { "type": "string" }, "symbol": { "type": "string" }, "system": { "type": "boolean" }, "to_canonical_factor": { "format": "double", "type": "number" }, "to_canonical_offset": { "format": "double", "type": "number" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "valid_to_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "id", "name" ], "type": "object" } } }, "description": "Registry entry created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Malformed entry or rejected override claim" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "registry-manage capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Dedupe gate found an exact or polarity variant" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Create a governed registry entry", "x-ordinate-capability": "registry-manage", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/registries/{kind}/entries/{id}": { "get": { "operationId": "get_v1_model_registries_by_kind_entries_by_id", "parameters": [ { "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "enum-concepts", "enum-sets", "quantity-kinds", "units", "link-types", "annotation-tags", "episode-roles" ], "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "canonical_unit_id": { "format": "uuid", "type": "string" }, "encoding": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "id": { "format": "uuid", "type": "string" }, "integrates_to": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "kind_id": { "format": "uuid", "type": "string" }, "members": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "name": { "type": "string" }, "rationale": { "type": "string" }, "symbol": { "type": "string" }, "system": { "type": "boolean" }, "to_canonical_factor": { "format": "double", "type": "number" }, "to_canonical_offset": { "format": "double", "type": "number" }, "tx_id": { "format": "int64", "type": "integer" }, "valid_from_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "valid_to_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "id", "name" ], "type": "object" } } }, "description": "Registry entry" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "read capability is not granted" }, "404": { "description": "Kind or entry not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read a governed registry entry", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" } }, "/v1/model/resolve": { "post": { "operationId": "post_v1_model_resolve", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "as_of_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "include_retired": { "type": "boolean" }, "range": { "anyOf": [ { "maxItems": 2, "minItems": 2, "prefixItems": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } ], "type": "array" }, { "type": "null" } ] }, "scope": { "additionalProperties": false, "properties": { "downstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] }, "template": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "id" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "name" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "under": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "path" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "upstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] } }, "required": [], "type": "object" }, "select": { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "kind": { "enum": [ "attributes_named" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "kind": { "enum": [ "attributes" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "assets" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ] } }, "required": [ "select", "scope" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "assets": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "effective_timezone": { "type": "string" }, "path": { "type": "string" }, "template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone_source_asset": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } }, "required": [ "asset_id", "path", "template_id", "timezone", "effective_timezone", "timezone_source_asset" ], "type": "object" }, "type": "array" }, "entries": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "attribute_id": { "format": "uuid", "type": "string" }, "continuity_class": { "type": "string" }, "display_unit_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "effective_timezone": { "type": "string" }, "enum_set_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "path": { "type": "string" }, "quantity_kind_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "segments": { "items": { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "series": { "format": "uuid", "type": "string" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "series", "start_ns", "end_ns" ], "type": "object" }, "type": "array" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone_source_asset": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "writer_class": { "type": "string" } }, "required": [ "attribute_id", "asset_id", "path", "timezone", "effective_timezone", "timezone_source_asset", "segments", "continuity_class", "writer_class", "enum_set_id", "quantity_kind_id", "display_unit_id" ], "type": "object" }, "type": "array" }, "model_as_of_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "unresolved": { "items": { "additionalProperties": false, "properties": { "asset_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" }, "requested_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "requested_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "asset_id", "path", "requested_name", "requested_id", "reason" ], "type": "object" }, "type": "array" } }, "required": [ "model_as_of_ns", "entries", "assets", "unresolved" ], "type": "object" } } }, "description": "Pinned resolved set" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid read request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured, unavailable, or render capacity is exhausted" } }, "summary": "Resolve model selectors to assets, attributes, and binding segments", "x-ordinate-capability": "read", "x-ordinate-scope": "each resolved result" } }, "/v1/model/resolve-path": { "get": { "operationId": "get_v1_model_resolve_path", "parameters": [ { "in": "query", "name": "path", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset", "attribute" ], "type": "string" } }, "required": [ "kind", "id" ], "type": "object" } } }, "description": "Resolved entity" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Path not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Resolve a composition path", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" } }, "/v1/model/staging": { "get": { "operationId": "get_v1_model_staging", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": false, "properties": { "first_seen_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "last_seen_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "series_uuid": { "format": "uuid", "type": "string" }, "source_uri": { "type": "string" }, "value_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "series_uuid", "source_uri", "value_type", "first_seen_ns", "last_seen_ns" ], "type": "object" }, "type": "array" } } }, "description": "Staging entries" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List staged unbound series", "x-ordinate-capability": "read", "x-ordinate-scope": "staging-root" } }, "/v1/model/templates": { "get": { "operationId": "get_v1_model_templates", "parameters": [ { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": false, "properties": { "attributes": { "items": { "maxItems": 2, "minItems": 2, "prefixItems": [ { "format": "uuid", "type": "string" }, { "additionalProperties": false, "properties": { "continuity_class": { "enum": [ "continuous", "stepped", "event" ], "type": "string" }, "default_unit_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "entry_cadence": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "enum_set_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "lifecycle_policy": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "limit_traits": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "name": { "type": "string" }, "overridable": { "items": { "type": "string" }, "type": "array" }, "quantity_kind_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "writer_class": { "enum": [ "collector", "calculated", "manual" ], "type": "string" } }, "required": [ "name", "quantity_kind_id", "default_unit_id", "continuity_class", "writer_class", "enum_set_id", "limit_traits", "lifecycle_policy", "entry_cadence", "overridable" ], "type": "object" } ], "type": "array" }, "type": "array" }, "name": { "type": "string" }, "notes": { "type": "string" }, "permitted_children": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "template_id": { "format": "uuid", "type": "string" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "template_id", "name", "permitted_children", "notes", "attributes", "tx_id" ], "type": "object" }, "type": "array" } } }, "description": "Templates" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List templates", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" }, "post": { "operationId": "post_v1_model_templates", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attributes": { "items": { "additionalProperties": false, "properties": { "continuity_class": { "enum": [ "continuous", "stepped", "event" ], "type": "string" }, "default_unit_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "entry_cadence": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "enum_set_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "lifecycle_policy": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "limit_traits": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "name": { "type": "string" }, "overridable": { "items": { "type": "string" }, "type": "array" }, "quantity_kind_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "writer_class": { "enum": [ "collector", "calculated", "manual" ], "type": "string" } }, "required": [ "name", "quantity_kind_id", "default_unit_id", "continuity_class", "writer_class", "enum_set_id", "limit_traits", "lifecycle_policy", "entry_cadence", "overridable" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "notes": { "type": "string" }, "permitted_children": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "reason": { "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attributes": { "items": { "maxItems": 2, "minItems": 2, "prefixItems": [ { "format": "uuid", "type": "string" }, { "additionalProperties": false, "properties": { "continuity_class": { "enum": [ "continuous", "stepped", "event" ], "type": "string" }, "default_unit_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "entry_cadence": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "enum_set_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "lifecycle_policy": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "limit_traits": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "name": { "type": "string" }, "overridable": { "items": { "type": "string" }, "type": "array" }, "quantity_kind_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "writer_class": { "enum": [ "collector", "calculated", "manual" ], "type": "string" } }, "required": [ "name", "quantity_kind_id", "default_unit_id", "continuity_class", "writer_class", "enum_set_id", "limit_traits", "lifecycle_policy", "entry_cadence", "overridable" ], "type": "object" } ], "type": "array" }, "type": "array" }, "name": { "type": "string" }, "notes": { "type": "string" }, "permitted_children": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "template_id": { "format": "uuid", "type": "string" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "template_id", "name", "permitted_children", "notes", "attributes", "tx_id" ], "type": "object" } } }, "description": "Created template" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid template" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Template name exists" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Create a template", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/templates/{uuid}": { "get": { "operationId": "get_v1_model_templates_by_uuid", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attributes": { "items": { "maxItems": 2, "minItems": 2, "prefixItems": [ { "format": "uuid", "type": "string" }, { "additionalProperties": false, "properties": { "continuity_class": { "enum": [ "continuous", "stepped", "event" ], "type": "string" }, "default_unit_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "entry_cadence": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "enum_set_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "lifecycle_policy": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "limit_traits": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "name": { "type": "string" }, "overridable": { "items": { "type": "string" }, "type": "array" }, "quantity_kind_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "writer_class": { "enum": [ "collector", "calculated", "manual" ], "type": "string" } }, "required": [ "name", "quantity_kind_id", "default_unit_id", "continuity_class", "writer_class", "enum_set_id", "limit_traits", "lifecycle_policy", "entry_cadence", "overridable" ], "type": "object" } ], "type": "array" }, "type": "array" }, "name": { "type": "string" }, "notes": { "type": "string" }, "permitted_children": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "template_id": { "format": "uuid", "type": "string" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "template_id", "name", "permitted_children", "notes", "attributes", "tx_id" ], "type": "object" } } }, "description": "Template" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Template not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read a template", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" }, "patch": { "operationId": "patch_v1_model_templates_by_uuid", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attributes": { "items": { "additionalProperties": false, "properties": { "continuity_class": { "enum": [ "continuous", "stepped", "event" ], "type": "string" }, "default_unit_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "entry_cadence": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "enum_set_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "lifecycle_policy": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "limit_traits": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "name": { "type": "string" }, "overridable": { "items": { "type": "string" }, "type": "array" }, "quantity_kind_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "writer_class": { "enum": [ "collector", "calculated", "manual" ], "type": "string" } }, "required": [ "name", "quantity_kind_id", "default_unit_id", "continuity_class", "writer_class", "enum_set_id", "limit_traits", "lifecycle_policy", "entry_cadence", "overridable" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "notes": { "type": "string" }, "permitted_children": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "reason": { "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "attributes": { "items": { "maxItems": 2, "minItems": 2, "prefixItems": [ { "format": "uuid", "type": "string" }, { "additionalProperties": false, "properties": { "continuity_class": { "enum": [ "continuous", "stepped", "event" ], "type": "string" }, "default_unit_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "entry_cadence": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "enum_set_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "lifecycle_policy": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "limit_traits": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "name": { "type": "string" }, "overridable": { "items": { "type": "string" }, "type": "array" }, "quantity_kind_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "writer_class": { "enum": [ "collector", "calculated", "manual" ], "type": "string" } }, "required": [ "name", "quantity_kind_id", "default_unit_id", "continuity_class", "writer_class", "enum_set_id", "limit_traits", "lifecycle_policy", "entry_cadence", "overridable" ], "type": "object" } ], "type": "array" }, "type": "array" }, "name": { "type": "string" }, "notes": { "type": "string" }, "permitted_children": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "template_id": { "format": "uuid", "type": "string" }, "tx_id": { "format": "int64", "type": "integer" } }, "required": [ "template_id", "name", "permitted_children", "notes", "attributes", "tx_id" ], "type": "object" } } }, "description": "Updated template" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid template" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Template not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Template conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Replace a template version", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/tree": { "get": { "operationId": "get_v1_model_tree", "parameters": [ { "in": "query", "name": "root", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "depth", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, { "in": "query", "name": "include_retired", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ModelTreeNode" }, "type": "array" } } }, "description": "Structural listing; authorization is currently coarse any-Read" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Root not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read the composition tree", "x-honest-oddity": "Structural listing is authenticated but currently coarse any-Read rather than per-node filtered", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" } }, "/v1/model/views": { "get": { "operationId": "get_v1_model_views", "parameters": [ { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "retired": { "type": "boolean" }, "tx_id": { "format": "int64", "type": "integer" }, "view_id": { "format": "uuid", "type": "string" } }, "required": [ "view_id", "name", "retired", "tx_id" ], "type": "object" }, "type": "array" } } }, "description": "Views" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List views", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" }, "post": { "operationId": "post_v1_model_views", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "retired": { "type": "boolean" }, "tx_id": { "format": "int64", "type": "integer" }, "view_id": { "format": "uuid", "type": "string" } }, "required": [ "view_id", "name", "retired", "tx_id" ], "type": "object" } } }, "description": "Created view" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "View name exists" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Create a view", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/views/{uuid}": { "get": { "operationId": "get_v1_model_views_by_uuid", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "retired": { "type": "boolean" }, "tx_id": { "format": "int64", "type": "integer" }, "view_id": { "format": "uuid", "type": "string" } }, "required": [ "view_id", "name", "retired", "tx_id" ], "type": "object" } } }, "description": "View" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "View not found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read a view", "x-ordinate-capability": "read", "x-ordinate-scope": "view-node path parameter `uuid`" }, "patch": { "operationId": "patch_v1_model_views_by_uuid", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "reason": { "type": "string" }, "rename": { "type": "string" }, "retire": { "type": "boolean" } }, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "retired": { "type": "boolean" }, "tx_id": { "format": "int64", "type": "integer" }, "view_id": { "format": "uuid", "type": "string" } }, "required": [ "view_id", "name", "retired", "tx_id" ], "type": "object" } } }, "description": "Updated view" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model edit capability is not granted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "View not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "View conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Rename or retire a view", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/model/views/{uuid}/tree": { "get": { "operationId": "get_v1_model_views_by_uuid_tree", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "as_of_ns", "required": false, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ViewTreeNode" }, "type": "array" } } }, "description": "View tree nodes" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read a view tree", "x-ordinate-capability": "read", "x-ordinate-scope": "view-node path parameter `uuid`" } }, "/v1/openapi.json": { "get": { "operationId": "get_v1_openapi.json", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "info": { "additionalProperties": true, "properties": { "title": { "type": "string" }, "version": { "type": "string" } }, "required": [ "title", "version" ], "type": "object" }, "openapi": { "type": "string" }, "paths": { "additionalProperties": true, "type": "object" } }, "required": [ "openapi", "info", "paths" ], "type": "object" } } }, "description": "OpenAPI 3.1 document generated from the executable route inventory" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required in enforced mode" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" } }, "summary": "Read the executable OpenAPI contract", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" } }, "/v1/operations": { "get": { "operationId": "get_v1_operations", "parameters": [ { "in": "query", "name": "kind", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "state", "required": false, "schema": { "enum": [ "queued", "running", "awaiting-commit", "completed", "cancelled", "failed" ], "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 1000, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "description": "Opaque cursor over exact (created_ns,namespaced operation ID) ordering", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "affected_resources": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "kind": { "type": "string" } }, "required": [ "kind", "id" ], "type": "object" }, "type": "array" }, "cancellable": { "type": "boolean" }, "completed_ns": { "anyOf": [ { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ] }, "created_ns": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "detail": { "description": "Adapter-specific identity and native state. New adapters add discriminated variants without changing the common operation fields.", "discriminator": { "propertyName": "adapter" }, "oneOf": [ { "additionalProperties": false, "properties": { "adapter": { "enum": [ "change-set" ], "type": "string" }, "change_set_id": { "format": "uuid", "type": "string" }, "change_set_state": { "enum": [ "preview", "committed", "cancelled", "failed" ], "type": "string" } }, "required": [ "adapter", "change_set_id", "change_set_state" ], "type": "object" } ] }, "error": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "estimated_work_remaining": { "anyOf": [ { "format": "int64", "minimum": 0, "type": "integer" }, { "type": "null" } ] }, "id": { "description": "Stable adapter-namespaced operation ID", "pattern": "^[a-z][a-z0-9.-]*:.+$", "type": "string" }, "kind": { "pattern": "^[a-z][a-z0-9.-]*(?:\\.[a-z0-9.-]+)+$", "type": "string" }, "principal": { "type": "string" }, "progress": { "additionalProperties": false, "properties": { "completed": { "format": "int64", "minimum": 0, "type": "integer" }, "total": { "anyOf": [ { "format": "int64", "minimum": 0, "type": "integer" }, { "type": "null" } ] }, "unit": { "type": "string" } }, "required": [ "completed", "total", "unit" ], "type": "object" }, "rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "reason": { "type": "string" }, "receipt": { "anyOf": [ { "discriminator": { "propertyName": "adapter" }, "oneOf": [ { "additionalProperties": false, "properties": { "adapter": { "enum": [ "change-set" ], "type": "string" }, "value": { "additionalProperties": false, "properties": { "audit_events": { "items": { "additionalProperties": false, "properties": { "action": { "enum": [ "rename" ], "type": "string" }, "entity_id": { "format": "uuid", "type": "string" }, "entity_kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "entity_kind", "entity_id", "action" ], "type": "object" }, "type": "array" }, "committed_operations": { "items": { "additionalProperties": false, "properties": { "kind": { "enum": [ "asset.rename" ], "type": "string" }, "resource_id": { "format": "uuid", "type": "string" }, "resource_kind": { "enum": [ "asset" ], "type": "string" }, "resulting_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" } }, "required": [ "kind", "resource_kind", "resource_id", "resulting_tx" ], "type": "object" }, "type": "array" }, "model_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "operation_id": { "pattern": "^change:[0-9a-fA-F-]{36}$", "type": "string" } }, "required": [ "operation_id", "model_tx", "committed_operations", "audit_events" ], "type": "object" } }, "required": [ "adapter", "value" ], "type": "object" } ] }, { "type": "null" } ] }, "source_change_set_id": { "description": "Required provenance link to the durable change set that initiated this operation", "format": "uuid", "type": "string" }, "stage": { "type": "string" }, "state": { "enum": [ "queued", "running", "awaiting-commit", "completed", "cancelled", "failed" ], "type": "string" } }, "required": [ "id", "kind", "principal", "reason", "source_change_set_id", "state", "stage", "progress", "rate", "estimated_work_remaining", "affected_resources", "cancellable", "created_ns", "completed_ns", "detail", "receipt", "error" ], "type": "object" }, "type": "array" }, "next_cursor": { "type": "string" } }, "required": [ "items" ], "type": "object" } } }, "description": "Stable keyset page" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid query, cursor, limit, namespace, or operation ID" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Operation not found or not visible to this principal" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Operations catalogue failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "List permission-filtered operations", "x-ordinate-capability": "authenticated", "x-ordinate-scope": "owner-or-admin" } }, "/v1/operations/{namespaced_id}": { "get": { "operationId": "get_v1_operations_by_namespaced_id", "parameters": [ { "in": "path", "name": "namespaced_id", "required": true, "schema": { "pattern": "^change:[0-9a-fA-F-]{36}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "affected_resources": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "kind": { "type": "string" } }, "required": [ "kind", "id" ], "type": "object" }, "type": "array" }, "cancellable": { "type": "boolean" }, "completed_ns": { "anyOf": [ { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ] }, "created_ns": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "detail": { "description": "Adapter-specific identity and native state. New adapters add discriminated variants without changing the common operation fields.", "discriminator": { "propertyName": "adapter" }, "oneOf": [ { "additionalProperties": false, "properties": { "adapter": { "enum": [ "change-set" ], "type": "string" }, "change_set_id": { "format": "uuid", "type": "string" }, "change_set_state": { "enum": [ "preview", "committed", "cancelled", "failed" ], "type": "string" } }, "required": [ "adapter", "change_set_id", "change_set_state" ], "type": "object" } ] }, "error": { "anyOf": [ { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, { "type": "null" } ] }, "estimated_work_remaining": { "anyOf": [ { "format": "int64", "minimum": 0, "type": "integer" }, { "type": "null" } ] }, "id": { "description": "Stable adapter-namespaced operation ID", "pattern": "^[a-z][a-z0-9.-]*:.+$", "type": "string" }, "kind": { "pattern": "^[a-z][a-z0-9.-]*(?:\\.[a-z0-9.-]+)+$", "type": "string" }, "principal": { "type": "string" }, "progress": { "additionalProperties": false, "properties": { "completed": { "format": "int64", "minimum": 0, "type": "integer" }, "total": { "anyOf": [ { "format": "int64", "minimum": 0, "type": "integer" }, { "type": "null" } ] }, "unit": { "type": "string" } }, "required": [ "completed", "total", "unit" ], "type": "object" }, "rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "reason": { "type": "string" }, "receipt": { "anyOf": [ { "discriminator": { "propertyName": "adapter" }, "oneOf": [ { "additionalProperties": false, "properties": { "adapter": { "enum": [ "change-set" ], "type": "string" }, "value": { "additionalProperties": false, "properties": { "audit_events": { "items": { "additionalProperties": false, "properties": { "action": { "enum": [ "rename" ], "type": "string" }, "entity_id": { "format": "uuid", "type": "string" }, "entity_kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "entity_kind", "entity_id", "action" ], "type": "object" }, "type": "array" }, "committed_operations": { "items": { "additionalProperties": false, "properties": { "kind": { "enum": [ "asset.rename" ], "type": "string" }, "resource_id": { "format": "uuid", "type": "string" }, "resource_kind": { "enum": [ "asset" ], "type": "string" }, "resulting_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" } }, "required": [ "kind", "resource_kind", "resource_id", "resulting_tx" ], "type": "object" }, "type": "array" }, "model_tx": { "description": "Exact signed 64-bit integer encoded as a decimal string", "pattern": "^-?[0-9]+$", "type": "string" }, "operation_id": { "pattern": "^change:[0-9a-fA-F-]{36}$", "type": "string" } }, "required": [ "operation_id", "model_tx", "committed_operations", "audit_events" ], "type": "object" } }, "required": [ "adapter", "value" ], "type": "object" } ] }, { "type": "null" } ] }, "source_change_set_id": { "description": "Required provenance link to the durable change set that initiated this operation", "format": "uuid", "type": "string" }, "stage": { "type": "string" }, "state": { "enum": [ "queued", "running", "awaiting-commit", "completed", "cancelled", "failed" ], "type": "string" } }, "required": [ "id", "kind", "principal", "reason", "source_change_set_id", "state", "stage", "progress", "rate", "estimated_work_remaining", "affected_resources", "cancellable", "created_ns", "completed_ns", "detail", "receipt", "error" ], "type": "object" } } }, "description": "Operation" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid query, cursor, limit, namespace, or operation ID" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Operation not found or not visible to this principal" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Operations catalogue failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured or unavailable" } }, "summary": "Read a permission-filtered operation", "x-ordinate-capability": "authenticated", "x-ordinate-scope": "owner-or-admin" } }, "/v1/read/as-of": { "post": { "operationId": "post_v1_read_as_of", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "annotations_cluster_px": { "minimum": 0, "type": "integer" }, "arrival_as_of_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "include_annotations": { "type": "boolean" }, "include_episodes": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "include_lineage": { "type": "boolean" }, "resolve": { "additionalProperties": false, "properties": { "as_of_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "include_retired": { "type": "boolean" }, "range": { "anyOf": [ { "maxItems": 2, "minItems": 2, "prefixItems": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } ], "type": "array" }, { "type": "null" } ] }, "scope": { "additionalProperties": false, "properties": { "downstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] }, "template": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "id" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "name" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "under": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "path" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "upstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] } }, "required": [], "type": "object" }, "select": { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "kind": { "enum": [ "attributes_named" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "kind": { "enum": [ "attributes" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "assets" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ] } }, "required": [ "select", "scope" ], "type": "object" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "resolve", "start_ns", "end_ns", "arrival_as_of_ns" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "attributes": { "items": { "additionalProperties": true, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "path": { "type": "string" }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "segments": { "items": { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "points": { "items": { "additionalProperties": false, "properties": { "quality": { "minimum": 0, "type": "integer" }, "ts_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "value": { "anyOf": [ { "type": "number" }, { "format": "int64", "type": "integer" }, { "type": "boolean" }, { "type": "string" }, { "additionalProperties": false, "properties": { "enum_set": { "type": "string" }, "ordinal": { "format": "int64", "type": "integer" } }, "required": [ "ordinal", "enum_set" ], "type": "object" } ] } }, "required": [ "ts_ns", "value", "quality" ], "type": "object" }, "type": "array" }, "series": { "format": "uuid", "type": "string" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "series", "start_ns", "end_ns", "points" ], "type": "object" }, "type": "array" } }, "required": [ "attribute_id", "path", "segments", "provenance" ], "type": "object" }, "type": "array" }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "unresolved": { "items": { "additionalProperties": false, "properties": { "asset_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" }, "requested_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "requested_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "asset_id", "path", "requested_name", "requested_id", "reason" ], "type": "object" }, "type": "array" } }, "required": [ "attributes", "unresolved", "provenance" ], "type": "object" } } }, "description": "Winning points as known at the arrival cutoff; suspect data remains a 200 with provenance flags" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid read request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured, unavailable, or render capacity is exhausted" } }, "summary": "Read the arrival-time view through model bindings", "x-ordinate-capability": "read", "x-ordinate-scope": "each resolved result" } }, "/v1/read/at": { "post": { "operationId": "post_v1_read_at", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "annotations_cluster_px": { "minimum": 0, "type": "integer" }, "extend_to_now": { "type": "boolean" }, "include_annotations": { "type": "boolean" }, "include_episodes": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "include_lineage": { "type": "boolean" }, "resolve": { "additionalProperties": false, "properties": { "as_of_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "include_retired": { "type": "boolean" }, "range": { "anyOf": [ { "maxItems": 2, "minItems": 2, "prefixItems": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } ], "type": "array" }, { "type": "null" } ] }, "scope": { "additionalProperties": false, "properties": { "downstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] }, "template": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "id" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "name" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "under": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "path" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "upstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] } }, "required": [], "type": "object" }, "select": { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "kind": { "enum": [ "attributes_named" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "kind": { "enum": [ "attributes" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "assets" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ] } }, "required": [ "select", "scope" ], "type": "object" }, "timestamp_format": { "enum": [ "legacy", "decimal-string" ], "type": "string" }, "timestamps_ns": { "items": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "Exact decimal i64 nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" } ] }, "type": "array" } }, "required": [ "resolve", "timestamps_ns" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "attributes": { "items": { "additionalProperties": true, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "continuity_class": { "type": "string" }, "path": { "type": "string" }, "points": { "items": { "oneOf": [ { "additionalProperties": true, "properties": { "extended": { "type": "boolean" }, "interpolated": { "type": "boolean" }, "quality": { "minimum": 0, "type": "integer" }, "ts_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "Exact decimal i64 nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" } ] }, "value": { "anyOf": [ { "type": "number" }, { "format": "int64", "type": "integer" }, { "type": "boolean" }, { "type": "string" }, { "additionalProperties": false, "properties": { "enum_set": { "type": "string" }, "ordinal": { "format": "int64", "type": "integer" } }, "required": [ "ordinal", "enum_set" ], "type": "object" } ] } }, "required": [ "ts_ns", "value", "quality", "interpolated" ], "type": "object" }, { "additionalProperties": false, "properties": { "no_value": { "enum": [ "before-data", "after-data", "gap", "bad", "unbound", "empty-window" ], "type": "string" }, "ts_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "Exact decimal i64 nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" } ] } }, "required": [ "ts_ns", "no_value" ], "type": "object" } ] }, "type": "array" }, "provenance": { "$ref": "#/components/schemas/Provenance" } }, "required": [ "attribute_id", "path", "continuity_class", "points", "provenance" ], "type": "object" }, "type": "array" }, "model_as_of_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "Exact decimal i64 nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" } ] }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "unresolved": { "items": { "additionalProperties": false, "properties": { "asset_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" }, "requested_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "requested_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "asset_id", "path", "requested_name", "requested_id", "reason" ], "type": "object" }, "type": "array" } }, "required": [ "model_as_of_ns", "attributes", "unresolved", "provenance" ], "type": "object" } } }, "description": "Per-instant values or explicit no_value reasons" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid read request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured, unavailable, or render capacity is exhausted" } }, "summary": "Evaluate attributes at explicit instants", "x-ordinate-capability": "read", "x-ordinate-scope": "each resolved result" } }, "/v1/read/episode-overlay": { "post": { "operationId": "post_v1_read_episode_overlay", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "episodes": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "mode": { "enum": [ "u-grid" ], "type": "string" }, "points": { "minimum": 0, "type": "integer" }, "resolve": { "additionalProperties": false, "properties": { "as_of_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "include_retired": { "type": "boolean" }, "range": { "anyOf": [ { "maxItems": 2, "minItems": 2, "prefixItems": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } ], "type": "array" }, { "type": "null" } ] }, "scope": { "additionalProperties": false, "properties": { "downstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] }, "template": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "id" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "name" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "under": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "path" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "upstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] } }, "required": [], "type": "object" }, "select": { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "kind": { "enum": [ "attributes_named" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "kind": { "enum": [ "attributes" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "assets" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ] } }, "required": [ "select", "scope" ], "type": "object" } }, "required": [ "resolve", "episodes", "points", "mode" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "episodes": { "items": { "additionalProperties": true, "properties": { "episode": { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "template": { "type": "string" } }, "required": [ "id", "name", "template", "start_ns", "end_ns" ], "type": "object" }, "series": { "items": { "additionalProperties": true, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "points": { "items": { "additionalProperties": true, "properties": { "interpolated": { "type": "boolean" }, "no_value": { "type": "string" }, "quality": { "minimum": 0, "type": "integer" }, "ts_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "u": { "format": "double", "type": "number" }, "value": { "anyOf": [ { "type": "number" }, { "format": "int64", "type": "integer" }, { "type": "boolean" }, { "type": "string" }, { "additionalProperties": false, "properties": { "enum_set": { "type": "string" }, "ordinal": { "format": "int64", "type": "integer" } }, "required": [ "ordinal", "enum_set" ], "type": "object" } ] } }, "required": [ "u", "ts_ns" ], "type": "object" }, "type": "array" }, "provenance": { "$ref": "#/components/schemas/Provenance" } }, "required": [ "attribute_id", "points", "provenance" ], "type": "object" }, "type": "array" } }, "required": [ "episode", "series" ], "type": "object" }, "type": "array" }, "unresolved_lives": { "items": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "type": "string" }, "reason": { "type": "string" } }, "required": [ "asset_id", "reason" ], "type": "object" }, "type": "array" } }, "required": [ "episodes" ], "type": "object" } } }, "description": "Episode overlays; unresolved_lives is emitted when life-over-life selection cannot fill requested lives" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid read request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured, unavailable, or render capacity is exhausted" } }, "summary": "Normalize closed episodes onto a 0..1 comparison grid", "x-ordinate-capability": "read", "x-ordinate-scope": "each resolved result" } }, "/v1/read/raw": { "post": { "operationId": "post_v1_read_raw", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "annotations_cluster_px": { "minimum": 0, "type": "integer" }, "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "include_annotations": { "type": "boolean" }, "include_episodes": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "include_lineage": { "type": "boolean" }, "resolve": { "additionalProperties": false, "properties": { "as_of_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "include_retired": { "type": "boolean" }, "range": { "anyOf": [ { "maxItems": 2, "minItems": 2, "prefixItems": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } ], "type": "array" }, { "type": "null" } ] }, "scope": { "additionalProperties": false, "properties": { "downstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] }, "template": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "id" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "name" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "under": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "path" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "upstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] } }, "required": [], "type": "object" }, "select": { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "kind": { "enum": [ "attributes_named" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "kind": { "enum": [ "attributes" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "assets" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ] } }, "required": [ "select", "scope" ], "type": "object" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "resolve", "start_ns", "end_ns" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "path": { "type": "string" }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "segments": { "items": { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "points": { "items": { "additionalProperties": false, "properties": { "quality": { "minimum": 0, "type": "integer" }, "ts_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "value": { "anyOf": [ { "type": "number" }, { "format": "int64", "type": "integer" }, { "type": "boolean" }, { "type": "string" }, { "additionalProperties": false, "properties": { "enum_set": { "type": "string" }, "ordinal": { "format": "int64", "type": "integer" } }, "required": [ "ordinal", "enum_set" ], "type": "object" } ] } }, "required": [ "ts_ns", "value", "quality" ], "type": "object" }, "type": "array" }, "series": { "format": "uuid", "type": "string" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "series", "start_ns", "end_ns", "points" ], "type": "object" }, "type": "array" } }, "required": [ "attribute_id", "path", "segments", "provenance" ], "type": "object" }, "type": "array" } } }, "description": "Bare per-attribute array; requested lineage, annotations, and episodes attach additively per attribute" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid read request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured, unavailable, or render capacity is exhausted" } }, "summary": "Read raw points through model bindings", "x-ordinate-capability": "read", "x-ordinate-scope": "each resolved result" } }, "/v1/read/raw-audit": { "post": { "operationId": "post_v1_read_raw_audit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "annotations_cluster_px": { "minimum": 0, "type": "integer" }, "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "include_annotations": { "type": "boolean" }, "include_episodes": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "include_lineage": { "type": "boolean" }, "resolve": { "additionalProperties": false, "properties": { "as_of_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "include_retired": { "type": "boolean" }, "range": { "anyOf": [ { "maxItems": 2, "minItems": 2, "prefixItems": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } ], "type": "array" }, { "type": "null" } ] }, "scope": { "additionalProperties": false, "properties": { "downstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] }, "template": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "id" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "name" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "under": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "path" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "upstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] } }, "required": [], "type": "object" }, "select": { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "kind": { "enum": [ "attributes_named" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "kind": { "enum": [ "attributes" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "assets" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ] } }, "required": [ "select", "scope" ], "type": "object" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "resolve", "start_ns", "end_ns" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "attributes": { "items": { "additionalProperties": true, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "path": { "type": "string" }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "segments": { "items": { "additionalProperties": false, "properties": { "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "points": { "items": { "additionalProperties": false, "properties": { "arrival_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "quality": { "minimum": 0, "type": "integer" }, "revision": { "minimum": 0, "type": "integer" }, "ts_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "value": { "anyOf": [ { "type": "number" }, { "format": "int64", "type": "integer" }, { "type": "boolean" }, { "type": "string" }, { "additionalProperties": false, "properties": { "enum_set": { "type": "string" }, "ordinal": { "format": "int64", "type": "integer" } }, "required": [ "ordinal", "enum_set" ], "type": "object" } ] } }, "required": [ "ts_ns", "revision", "arrival_ns", "value", "quality" ], "type": "object" }, "type": "array" }, "series": { "format": "uuid", "type": "string" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "series", "start_ns", "end_ns", "points" ], "type": "object" }, "type": "array" } }, "required": [ "attribute_id", "path", "segments", "provenance" ], "type": "object" }, "type": "array" }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "unresolved": { "items": { "additionalProperties": false, "properties": { "asset_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" }, "requested_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "requested_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "asset_id", "path", "requested_name", "requested_id", "reason" ], "type": "object" }, "type": "array" } }, "required": [ "attributes", "unresolved", "provenance" ], "type": "object" } } }, "description": "Audit revisions and partial-data provenance" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid read request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured, unavailable, or render capacity is exhausted" } }, "summary": "Read all revisions through model bindings", "x-ordinate-capability": "read", "x-ordinate-scope": "each resolved result" } }, "/v1/read/render": { "post": { "operationId": "post_v1_read_render", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "annotations_cluster_px": { "minimum": 0, "type": "integer" }, "end_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "Exact decimal i64 nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" } ] }, "include_annotations": { "type": "boolean" }, "include_episodes": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "include_lineage": { "type": "boolean" }, "mode": { "enum": [ "significant-points", "minmax-band" ], "type": "string" }, "resolve": { "additionalProperties": false, "properties": { "as_of_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "include_retired": { "type": "boolean" }, "range": { "anyOf": [ { "maxItems": 2, "minItems": 2, "prefixItems": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } ], "type": "array" }, { "type": "null" } ] }, "scope": { "additionalProperties": false, "properties": { "downstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] }, "template": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "id" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "name" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "under": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "path" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "upstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] } }, "required": [], "type": "object" }, "select": { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "kind": { "enum": [ "attributes_named" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "kind": { "enum": [ "attributes" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "assets" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ] } }, "required": [ "select", "scope" ], "type": "object" }, "start_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "Exact decimal i64 nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" } ] }, "timestamp_format": { "enum": [ "legacy", "decimal-string" ], "type": "string" }, "width": { "minimum": 0, "type": "integer" } }, "required": [ "resolve", "start_ns", "end_ns", "width" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "attributes": { "items": { "additionalProperties": true, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "mode": { "enum": [ "significant-points", "minmax-band" ], "type": "string" }, "path": { "type": "string" }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "t_ms": { "items": { "format": "double", "type": "number" }, "type": "array" } }, "required": [ "attribute_id", "path", "mode", "t_ms", "provenance" ], "type": "object" }, "type": "array" }, "model_as_of_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "Exact decimal i64 nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" } ] }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "unresolved": { "items": { "additionalProperties": false, "properties": { "asset_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" }, "requested_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "requested_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "asset_id", "path", "requested_name", "requested_id", "reason" ], "type": "object" }, "type": "array" } }, "required": [ "model_as_of_ns", "attributes", "unresolved", "provenance" ], "type": "object" } } }, "description": "Per-attribute significant-points or min/max bands. decimal-string adds exact t_ns, quality, gap, edge, and provenance metadata without changing legacy mode" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid read request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Configured span, attribute, or decode-row limit exceeded" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured, unavailable, or render capacity is exhausted" } }, "summary": "Render model-addressed attributes for a pixel width", "x-honest-oddity": "Partial, provisional, lossy, quarantined, and clock-suspect data are successful 200 responses with explicit provenance; admission limits use 413/503", "x-ordinate-capability": "read", "x-ordinate-scope": "each resolved result" } }, "/v1/read/sampled": { "post": { "operationId": "post_v1_read_sampled", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "annotations_cluster_px": { "minimum": 0, "type": "integer" }, "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "extend_to_now": { "type": "boolean" }, "include_annotations": { "type": "boolean" }, "include_episodes": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "include_lineage": { "type": "boolean" }, "interval_ns": { "format": "int64", "type": "integer" }, "resolve": { "additionalProperties": false, "properties": { "as_of_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "include_retired": { "type": "boolean" }, "range": { "anyOf": [ { "maxItems": 2, "minItems": 2, "prefixItems": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } ], "type": "array" }, { "type": "null" } ] }, "scope": { "additionalProperties": false, "properties": { "downstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] }, "template": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "id" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "name" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "under": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "path" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "upstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] } }, "required": [], "type": "object" }, "select": { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "kind": { "enum": [ "attributes_named" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "kind": { "enum": [ "attributes" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "assets" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ] } }, "required": [ "select", "scope" ], "type": "object" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "resolve", "start_ns", "end_ns", "interval_ns" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "attributes": { "items": { "additionalProperties": true, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "continuity_class": { "type": "string" }, "path": { "type": "string" }, "points": { "items": { "oneOf": [ { "additionalProperties": true, "properties": { "extended": { "type": "boolean" }, "interpolated": { "type": "boolean" }, "quality": { "minimum": 0, "type": "integer" }, "ts_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "Exact decimal i64 nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" } ] }, "value": { "anyOf": [ { "type": "number" }, { "format": "int64", "type": "integer" }, { "type": "boolean" }, { "type": "string" }, { "additionalProperties": false, "properties": { "enum_set": { "type": "string" }, "ordinal": { "format": "int64", "type": "integer" } }, "required": [ "ordinal", "enum_set" ], "type": "object" } ] } }, "required": [ "ts_ns", "value", "quality", "interpolated" ], "type": "object" }, { "additionalProperties": false, "properties": { "no_value": { "enum": [ "before-data", "after-data", "gap", "bad", "unbound", "empty-window" ], "type": "string" }, "ts_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "Exact decimal i64 nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" } ] } }, "required": [ "ts_ns", "no_value" ], "type": "object" } ] }, "type": "array" }, "provenance": { "$ref": "#/components/schemas/Provenance" } }, "required": [ "attribute_id", "path", "continuity_class", "points", "provenance" ], "type": "object" }, "type": "array" }, "model_as_of_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "Exact decimal i64 nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" } ] }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "unresolved": { "items": { "additionalProperties": false, "properties": { "asset_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" }, "requested_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "requested_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "asset_id", "path", "requested_name", "requested_id", "reason" ], "type": "object" }, "type": "array" } }, "required": [ "model_as_of_ns", "attributes", "unresolved", "provenance" ], "type": "object" } } }, "description": "Same shape as read/at; instants are start + n*interval strictly before end" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid read request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured, unavailable, or render capacity is exhausted" } }, "summary": "Evaluate attributes on a regular sample grid", "x-ordinate-capability": "read", "x-ordinate-scope": "each resolved result" } }, "/v1/read/snapshot": { "post": { "operationId": "post_v1_read_snapshot", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "annotations_cluster_px": { "minimum": 0, "type": "integer" }, "include_annotations": { "type": "boolean" }, "include_episodes": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "include_lineage": { "type": "boolean" }, "resolve": { "additionalProperties": false, "properties": { "as_of_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "include_retired": { "type": "boolean" }, "range": { "anyOf": [ { "maxItems": 2, "minItems": 2, "prefixItems": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } ], "type": "array" }, { "type": "null" } ] }, "scope": { "additionalProperties": false, "properties": { "downstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] }, "template": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "id" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "name" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "under": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "path" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "upstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] } }, "required": [], "type": "object" }, "select": { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "kind": { "enum": [ "attributes_named" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "kind": { "enum": [ "attributes" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "assets" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ] } }, "required": [ "select", "scope" ], "type": "object" } }, "required": [ "resolve" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "path": { "type": "string" }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "snapshot": { "anyOf": [ { "additionalProperties": false, "properties": { "quality": { "minimum": 0, "type": "integer" }, "ts_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "value": { "anyOf": [ { "type": "number" }, { "format": "int64", "type": "integer" }, { "type": "boolean" }, { "type": "string" }, { "additionalProperties": false, "properties": { "enum_set": { "type": "string" }, "ordinal": { "format": "int64", "type": "integer" } }, "required": [ "ordinal", "enum_set" ], "type": "object" } ] } }, "required": [ "ts_ns", "value", "quality" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "attribute_id", "path", "snapshot", "provenance" ], "type": "object" }, "type": "array" } } }, "description": "Bare per-attribute array; unbound attributes have snapshot:null" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid read request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured, unavailable, or render capacity is exhausted" } }, "summary": "Read the current point through model bindings", "x-ordinate-capability": "read", "x-ordinate-scope": "each resolved result" } }, "/v1/read/subscribe": { "post": { "operationId": "post_v1_read_subscribe", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "include_snapshot": { "type": "boolean" }, "resolve": { "additionalProperties": false, "properties": { "as_of_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "include_retired": { "type": "boolean" }, "range": { "anyOf": [ { "maxItems": 2, "minItems": 2, "prefixItems": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } ], "type": "array" }, { "type": "null" } ] }, "scope": { "additionalProperties": false, "properties": { "downstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] }, "template": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "id" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "name" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "under": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "path" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "upstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] } }, "required": [], "type": "object" }, "select": { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "kind": { "enum": [ "attributes_named" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "kind": { "enum": [ "attributes" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "assets" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ] } }, "required": [ "select", "scope" ], "type": "object" }, "timestamp_format": { "enum": [ "legacy", "decimal-string" ], "type": "string" } }, "required": [ "resolve" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } } }, "description": "SSE events: resolved, frame, gap, and lagged" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid read request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured, unavailable, or render capacity is exhausted" } }, "summary": "Subscribe to resolved live updates over SSE", "x-ordinate-capability": "read", "x-ordinate-scope": "each resolved result", "x-streaming": { "documentation": "docs/api/streaming.md", "events": [ "resolved", "frame", "gap", "lagged" ], "resolution": "pinned at connect", "scope_rechecked": "on reconnect", "transport": "sse" } } }, "/v1/read/summary": { "post": { "operationId": "post_v1_read_summary", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "annotations_cluster_px": { "minimum": 0, "type": "integer" }, "basis": { "enum": [ "default", "time-weighted", "event-weighted" ], "type": "string" }, "compat": { "enum": [ "pi" ], "type": "string" }, "compat_options": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "duration_in": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "end_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "Exact decimal i64 nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" } ] }, "filter": { "type": "string" }, "fns": { "items": { "type": "string" }, "type": "array" }, "include_annotations": { "type": "boolean" }, "include_episodes": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "include_lineage": { "type": "boolean" }, "resolve": { "additionalProperties": false, "properties": { "as_of_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "include_retired": { "type": "boolean" }, "range": { "anyOf": [ { "maxItems": 2, "minItems": 2, "prefixItems": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } ], "type": "array" }, { "type": "null" } ] }, "scope": { "additionalProperties": false, "properties": { "downstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] }, "template": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "id" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "name" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "under": { "anyOf": [ { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "type": "string" }, "kind": { "enum": [ "path" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "asset" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" } ] }, { "type": "null" } ] }, "upstream_of": { "anyOf": [ { "additionalProperties": false, "properties": { "asset": { "format": "uuid", "type": "string" }, "depth": { "minimum": 0, "type": "integer" }, "via": { "items": { "type": "string" }, "type": "array" } }, "required": [ "asset", "via" ], "type": "object" }, { "type": "null" } ] } }, "required": [], "type": "object" }, "select": { "oneOf": [ { "additionalProperties": false, "properties": { "content": { "additionalProperties": false, "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "kind": { "enum": [ "attributes_named" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "content": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "kind": { "enum": [ "attributes" ], "type": "string" } }, "required": [ "kind", "content" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "enum": [ "assets" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ] } }, "required": [ "select", "scope" ], "type": "object" }, "start_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "Exact decimal i64 nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" } ] }, "timestamp_format": { "enum": [ "legacy", "decimal-string" ], "type": "string" }, "window": { "anyOf": [ { "$ref": "#/components/schemas/WindowSpec" }, { "type": "null" } ] } }, "required": [ "resolve", "start_ns", "end_ns", "fns" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "attributes": { "items": { "additionalProperties": true, "properties": { "attribute_id": { "format": "uuid", "type": "string" }, "path": { "type": "string" }, "windows": { "items": { "additionalProperties": true, "properties": { "end_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "Exact decimal i64 nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" } ] }, "nulls": { "additionalProperties": { "type": "string" }, "type": "object" }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "start_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "Exact decimal i64 nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" } ] }, "values": { "additionalProperties": { "anyOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "type": "null" } ], "description": "Arbitrary JSON value" }, "type": "object" } }, "required": [ "start_ns", "end_ns", "values", "nulls", "provenance" ], "type": "object" }, "type": "array" } }, "required": [ "attribute_id", "path", "windows" ], "type": "object" }, "type": "array" }, "model_as_of_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "description": "Exact decimal i64 nanoseconds", "pattern": "^-?[0-9]+$", "type": "string" } ] }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "unresolved": { "items": { "additionalProperties": false, "properties": { "asset_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" }, "requested_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "requested_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "asset_id", "path", "requested_name", "requested_id", "reason" ], "type": "object" }, "type": "array" } }, "required": [ "model_as_of_ns", "attributes", "unresolved", "provenance" ], "type": "object" } } }, "description": "Window values/null reasons and provenance; suspect or partial data is recorded and flagged on 200" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid read request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model database is not configured, unavailable, or render capacity is exhausted" } }, "summary": "Calculate windowed summaries through model bindings", "x-ordinate-capability": "read", "x-ordinate-scope": "each resolved result" } }, "/v1/series": { "get": { "operationId": "get_v1_series", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "description": "Opaque keyset cursor returned as next_cursor by the preceding page", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "description": "Activates the paginated response envelope; values above 1000 are rejected", "maximum": 1000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Without cursor or limit the legacy response is a bare array. Supplying either pagination query returns an object containing items and, when another page exists, next_cursor.", "oneOf": [ { "items": { "additionalProperties": false, "properties": { "rollups_enabled": { "type": "boolean" }, "series_uuid": { "format": "uuid", "type": "string" }, "source_uri": { "type": "string" }, "staged": { "type": "boolean" }, "value_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "writable_class": { "enum": [ "standard", "forecast" ], "type": "string" } }, "required": [ "series_uuid", "source_uri", "staged", "value_type", "writable_class", "rollups_enabled" ], "type": "object" }, "type": "array" }, { "additionalProperties": false, "properties": { "items": { "items": { "additionalProperties": false, "properties": { "rollups_enabled": { "type": "boolean" }, "series_uuid": { "format": "uuid", "type": "string" }, "source_uri": { "type": "string" }, "staged": { "type": "boolean" }, "value_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "writable_class": { "enum": [ "standard", "forecast" ], "type": "string" } }, "required": [ "series_uuid", "source_uri", "staged", "value_type", "writable_class", "rollups_enabled" ], "type": "object" }, "type": "array" }, "next_cursor": { "type": "string" } }, "required": [ "items" ], "type": "object" } ] } } }, "description": "Series registry entries; unreadable series are absent. The response is a bare array unless cursor or limit activates keyset pagination." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid cursor or pagination limit above 1000" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" } }, "summary": "List registered series visible to the caller", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere" } }, "/v1/series/{uuid}/chunks": { "get": { "operationId": "get_v1_series_by_uuid_chunks", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "start_ns", "required": true, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, { "in": "query", "name": "end_ns", "required": true, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": false, "properties": { "chunk_id": { "format": "int64", "type": "integer" }, "count": { "minimum": 0, "type": "integer" }, "format_version": { "minimum": 0, "type": "integer" }, "has_revisions": { "type": "boolean" }, "lossy_tag": { "type": "string" }, "space": { "type": "string" }, "state": { "type": "string" }, "t_max": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "t_min": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "tier": { "type": "string" } }, "required": [ "chunk_id", "space", "tier", "format_version", "t_min", "t_max", "count", "has_revisions", "lossy_tag", "state" ], "type": "object" }, "type": "array" } } }, "description": "Chunk diagnostics" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "Invalid UUID or range" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" } }, "summary": "List storage chunks for a series and range", "x-ordinate-capability": "read", "x-ordinate-scope": "owning asset of series path parameter `uuid`, or staging-root" } }, "/v1/series/{uuid}/finalised": { "get": { "operationId": "get_v1_series_by_uuid_finalised", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "finalised_through_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "finalised_through_ns" ], "type": "object" } } }, "description": "Finalisation watermark" }, "400": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Invalid series UUID" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" } }, "summary": "Read the finalisation watermark", "x-ordinate-capability": "read", "x-ordinate-scope": "owning asset of series path parameter `uuid`, or staging-root" } }, "/v1/series/{uuid}/gaps": { "get": { "operationId": "get_v1_series_by_uuid_gaps", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "start_ns", "required": true, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, { "in": "query", "name": "end_ns", "required": true, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, { "in": "query", "name": "stat", "required": false, "schema": { "enum": [ "count", "min", "max", "first", "last", "twa", "percent_good" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "gaps": { "items": { "additionalProperties": false, "properties": { "cause": { "type": "string" }, "detail": { "type": "string" }, "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns", "cause", "detail" ], "type": "object" }, "type": "array" } }, "required": [ "gaps" ], "type": "object" } } }, "description": "Recorded gaps" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "Invalid UUID or range" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" } }, "summary": "Read recorded gap markers", "x-ordinate-capability": "read", "x-ordinate-scope": "owning asset of series path parameter `uuid`, or staging-root" } }, "/v1/series/{uuid}/lifecycle-policy": { "get": { "operationId": "get_v1_series_by_uuid_lifecycle_policy", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "policy": { "anyOf": [ { "additionalProperties": false, "properties": { "annotations": { "additionalProperties": false, "properties": { "keep": { "enum": [ "forever" ], "type": "string" } }, "required": [ "keep" ], "type": "object" }, "raw": { "oneOf": [ { "additionalProperties": false, "properties": { "keep": { "enum": [ "forever" ], "type": "string" } }, "required": [ "keep" ], "type": "object" }, { "additionalProperties": false, "properties": { "keep_days": { "minimum": 0, "type": "integer" }, "then": { "enum": [ "swinging-door" ], "type": "string" } }, "required": [ "keep_days", "then" ], "type": "object" } ] }, "rollups": { "additionalProperties": false, "properties": { "keep": { "enum": [ "forever" ], "type": "string" } }, "required": [ "keep" ], "type": "object" }, "schema": { "enum": [ "ordinate-lifecycle-policy/v1" ], "type": "string" }, "swinging_door": { "additionalProperties": false, "properties": { "maxdev_percent_of_range": { "format": "double", "type": "number" }, "range_max": { "format": "double", "type": "number" }, "range_min": { "format": "double", "type": "number" } }, "required": [ "maxdev_percent_of_range", "range_min", "range_max" ], "type": "object" } }, "required": [ "schema", "raw", "rollups", "annotations" ], "type": "object" }, { "type": "null" } ] }, "version": { "anyOf": [ { "format": "int64", "type": "integer" }, { "type": "null" } ] } }, "required": [ "policy", "version" ], "type": "object" } } }, "description": "Current policy and version; both are null when absent" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" } }, "summary": "Read a series lifecycle policy", "x-ordinate-capability": "read", "x-ordinate-scope": "owning asset of series path parameter `uuid`, or staging-root" }, "put": { "operationId": "put_v1_series_by_uuid_lifecycle_policy", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "annotations": { "additionalProperties": false, "properties": { "keep": { "enum": [ "forever" ], "type": "string" } }, "required": [ "keep" ], "type": "object" }, "raw": { "oneOf": [ { "additionalProperties": false, "properties": { "keep": { "enum": [ "forever" ], "type": "string" } }, "required": [ "keep" ], "type": "object" }, { "additionalProperties": false, "properties": { "keep_days": { "minimum": 0, "type": "integer" }, "then": { "enum": [ "swinging-door" ], "type": "string" } }, "required": [ "keep_days", "then" ], "type": "object" } ] }, "rollups": { "additionalProperties": false, "properties": { "keep": { "enum": [ "forever" ], "type": "string" } }, "required": [ "keep" ], "type": "object" }, "schema": { "enum": [ "ordinate-lifecycle-policy/v1" ], "type": "string" }, "swinging_door": { "additionalProperties": false, "properties": { "maxdev_percent_of_range": { "format": "double", "type": "number" }, "range_max": { "format": "double", "type": "number" }, "range_min": { "format": "double", "type": "number" } }, "required": [ "maxdev_percent_of_range", "range_min", "range_max" ], "type": "object" } }, "required": [ "schema", "raw", "rollups", "annotations" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "Lifecycle policy stored" }, "400": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Malformed or invalid lifecycle policy" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model-edit capability is not granted for this series" } }, "summary": "Replace a series lifecycle policy", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/series/{uuid}/raw": { "get": { "operationId": "get_v1_series_by_uuid_raw", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "start_ns", "required": true, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, { "in": "query", "name": "end_ns", "required": true, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, { "in": "query", "name": "stat", "required": false, "schema": { "enum": [ "count", "min", "max", "first", "last", "twa", "percent_good" ], "type": "string" } }, { "in": "query", "name": "include_gaps", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "gaps": { "items": { "additionalProperties": false, "properties": { "cause": { "type": "string" }, "detail": { "type": "string" }, "end_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "start_ns", "end_ns", "cause", "detail" ], "type": "object" }, "type": "array" }, "points": { "items": { "additionalProperties": false, "properties": { "quality": { "minimum": 0, "type": "integer" }, "ts_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "value": { "anyOf": [ { "type": "number" }, { "format": "int64", "type": "integer" }, { "type": "boolean" }, { "type": "string" }, { "additionalProperties": false, "properties": { "enum_set": { "type": "string" }, "ordinal": { "format": "int64", "type": "integer" } }, "required": [ "ordinal", "enum_set" ], "type": "object" } ], "description": "Native typed value: number, boolean, string, or digital ordinal" } }, "required": [ "ts_ns", "value", "quality" ], "type": "object" }, "type": "array" } }, "required": [ "points" ], "type": "object" } } }, "description": "Merged points; gaps is present only when include_gaps=true" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "Invalid UUID, range, or statistic" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" } }, "summary": "Read merged raw series points", "x-ordinate-capability": "read", "x-ordinate-scope": "owning asset of series path parameter `uuid`, or staging-root" } }, "/v1/series/{uuid}/raw-audit": { "get": { "operationId": "get_v1_series_by_uuid_raw_audit", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "start_ns", "required": true, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, { "in": "query", "name": "end_ns", "required": true, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, { "in": "query", "name": "stat", "required": false, "schema": { "enum": [ "count", "min", "max", "first", "last", "twa", "percent_good" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "points": { "items": { "additionalProperties": false, "properties": { "arrival_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "quality": { "minimum": 0, "type": "integer" }, "revision": { "minimum": 0, "type": "integer" }, "ts_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "value": { "anyOf": [ { "type": "number" }, { "format": "int64", "type": "integer" }, { "type": "boolean" }, { "type": "string" }, { "additionalProperties": false, "properties": { "enum_set": { "type": "string" }, "ordinal": { "format": "int64", "type": "integer" } }, "required": [ "ordinal", "enum_set" ], "type": "object" } ], "description": "Native typed value: number, boolean, string, or digital ordinal" } }, "required": [ "ts_ns", "revision", "arrival_ns", "value", "quality" ], "type": "object" }, "type": "array" }, "series": { "format": "uuid", "type": "string" } }, "required": [ "series", "points" ], "type": "object" } } }, "description": "Revision order is the audit record" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "Invalid UUID or range" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" } }, "summary": "Read every stored revision in audit order", "x-ordinate-capability": "read", "x-ordinate-scope": "owning asset of series path parameter `uuid`, or staging-root" } }, "/v1/series/{uuid}/render": { "get": { "operationId": "get_v1_series_by_uuid_render", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "start_ns", "required": true, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, { "in": "query", "name": "end_ns", "required": true, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, { "in": "query", "name": "width", "required": true, "schema": { "minimum": 0, "type": "integer" } }, { "in": "query", "name": "mode", "required": false, "schema": { "enum": [ "significant-points", "minmax-band" ], "type": "string" } }, { "in": "query", "name": "stat", "required": false, "schema": { "enum": [ "count", "min", "max", "first", "last", "twa", "percent_good" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "additionalProperties": false, "properties": { "provenance": { "additionalProperties": false, "properties": { "mode": { "enum": [ "significant-points" ], "type": "string" }, "percentGood": { "format": "double", "type": "number" }, "pointsScanned": { "minimum": 0, "type": "integer" } }, "required": [ "percentGood", "mode", "pointsScanned" ], "type": "object" }, "t_ms": { "items": { "format": "double", "type": "number" }, "type": "array" }, "transitions": { "items": { "additionalProperties": false, "properties": { "kind": { "enum": [ "good-bad", "bad-good", "good-uncertain", "uncertain-good", "uncertain-bad", "bad-uncertain" ], "type": "string" }, "t_ms": { "format": "double", "type": "number" } }, "required": [ "t_ms", "kind" ], "type": "object" }, "type": "array" }, "v": { "items": { "format": "double", "type": "number" }, "type": "array" } }, "required": [ "t_ms", "v", "provenance", "transitions" ], "type": "object" }, { "additionalProperties": false, "properties": { "percent_good": { "format": "double", "type": "number" }, "points_scanned": { "minimum": 0, "type": "integer" }, "t_ms": { "items": { "format": "double", "type": "number" }, "type": "array" }, "transitions": { "items": { "additionalProperties": false, "properties": { "kind": { "enum": [ "good-bad", "bad-good", "good-uncertain", "uncertain-good", "uncertain-bad", "bad-uncertain" ], "type": "string" }, "t_ms": { "format": "double", "type": "number" } }, "required": [ "t_ms", "kind" ], "type": "object" }, "type": "array" }, "v_max": { "items": { "format": "double", "type": "number" }, "type": "array" }, "v_min": { "items": { "format": "double", "type": "number" }, "type": "array" } }, "required": [ "t_ms", "v_min", "v_max", "percent_good", "points_scanned", "transitions" ], "type": "object" } ] } } }, "description": "Significant-points or min/max-band rendering; t_ms intentionally uses float milliseconds" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "Invalid UUID, range, render mode, statistic, or string series" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" } }, "summary": "Render a numeric series for a pixel width", "x-ordinate-capability": "read", "x-ordinate-scope": "owning asset of series path parameter `uuid`, or staging-root" } }, "/v1/series/{uuid}/rollups": { "get": { "operationId": "get_v1_series_by_uuid_rollups", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "tier", "required": true, "schema": { "enum": [ "1h", "1d" ], "type": "string" } }, { "in": "query", "name": "start_ns", "required": true, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, { "in": "query", "name": "end_ns", "required": true, "schema": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "rows": { "items": { "additionalProperties": false, "properties": { "count": { "format": "int64", "type": "integer" }, "finalised_at_ns": { "anyOf": [ { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, { "type": "null" } ] }, "first": { "anyOf": [ { "format": "double", "type": "number" }, { "type": "null" } ] }, "good_time_ns": { "format": "int64", "type": "integer" }, "last": { "anyOf": [ { "format": "double", "type": "number" }, { "type": "null" } ] }, "max": { "anyOf": [ { "format": "double", "type": "number" }, { "type": "null" } ] }, "min": { "anyOf": [ { "format": "double", "type": "number" }, { "type": "null" } ] }, "percent_good": { "format": "double", "type": "number" }, "sum": { "anyOf": [ { "format": "double", "type": "number" }, { "type": "null" } ] }, "tw_sum_linear": { "format": "double", "type": "number" }, "tw_sum_stepped": { "format": "double", "type": "number" }, "window_start_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" } }, "required": [ "window_start_ns", "count", "min", "max", "sum", "tw_sum_linear", "tw_sum_stepped", "first", "last", "good_time_ns", "percent_good", "finalised_at_ns" ], "type": "object" }, "type": "array" } }, "required": [ "rows" ], "type": "object" } } }, "description": "Raw rollup rows; percent_good is the stored 0-1 fraction" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "Invalid UUID, tier, or range" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" } }, "summary": "Read stored rollup rows", "x-ordinate-capability": "read", "x-ordinate-scope": "owning asset of series path parameter `uuid`, or staging-root" } }, "/v1/series/{uuid}/snapshot": { "get": { "operationId": "get_v1_series_by_uuid_snapshot", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "stat", "required": false, "schema": { "enum": [ "count", "min", "max", "first", "last", "twa", "percent_good" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "quality": { "minimum": 0, "type": "integer" }, "ts_ns": { "description": "UTC Unix timestamp in nanoseconds", "format": "int64", "type": "integer" }, "value": { "anyOf": [ { "type": "number" }, { "format": "int64", "type": "integer" }, { "type": "boolean" }, { "type": "string" }, { "additionalProperties": false, "properties": { "enum_set": { "type": "string" }, "ordinal": { "format": "int64", "type": "integer" } }, "required": [ "ordinal", "enum_set" ], "type": "object" } ], "description": "Native typed value: number, boolean, string, or digital ordinal" } }, "required": [ "ts_ns", "value", "quality" ], "type": "object" } } }, "description": "Latest point" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "Invalid UUID or statistic" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "404": { "description": "Series has no point" } }, "summary": "Read the latest series point", "x-ordinate-capability": "read", "x-ordinate-scope": "owning asset of series path parameter `uuid`, or staging-root" } }, "/v1/series/{uuid}/writable-class": { "put": { "operationId": "put_v1_series_by_uuid_writable_class", "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "class": { "enum": [ "standard", "forecast" ], "type": "string" } }, "required": [ "class" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "Writable class updated" }, "400": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Invalid UUID or writable class" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model-edit capability is not granted for this series" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Model transaction conflict" } }, "summary": "Set the series writable class", "x-ordinate-capability": "model-edit", "x-ordinate-scope": "handler-resolved target" } }, "/v1/stream": { "get": { "operationId": "get_v1_stream", "parameters": [ { "in": "query", "name": "series", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "101": { "description": "WebSocket upgrade" }, "400": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Missing or malformed series UUID query" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Read capability is not granted" }, "426": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "WebSocket upgrade headers are required" } }, "summary": "Stream live series updates over WebSocket", "x-ordinate-capability": "read", "x-ordinate-scope": "held anywhere", "x-streaming": { "documentation": "docs/api/streaming.md", "frames": [ { "additionalProperties": false, "properties": { "quality": { "minimum": 0, "type": "integer" }, "series": { "format": "uuid", "type": "string" }, "t_ms": { "format": "double", "type": "number" }, "ts_ns": { "type": "string" }, "type": { "enum": [ "point" ], "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "format": "int64", "type": "integer" }, { "type": "boolean" }, { "type": "string" }, { "additionalProperties": false, "properties": { "enum_set": { "type": "string" }, "ordinal": { "format": "int64", "type": "integer" } }, "required": [ "ordinal", "enum_set" ], "type": "object" } ], "description": "Native typed value: number, boolean, string, or digital ordinal" } }, "required": [ "type", "series", "t_ms", "ts_ns", "value", "quality" ], "type": "object" }, { "additionalProperties": false, "properties": { "cause": { "type": "string" }, "end_ns": { "type": "string" }, "series": { "format": "uuid", "type": "string" }, "start_ns": { "type": "string" }, "type": { "enum": [ "gap" ], "type": "string" } }, "required": [ "type", "series", "start_ns", "end_ns", "cause" ], "type": "object" } ], "lag_behavior": "best effort; lagged frames are skipped", "scope_rechecked": "on reconnect", "transport": "websocket" } } } }, "security": [ { "bearer": [] }, { "sessionCookie": [] } ], "servers": [ { "description": "same-origin", "url": "/" } ] }