{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "L3 Backups public API", "version": "1.0.0", "description": "Public API v1 (released). Use the tenant HTTPS host.\nOnly Authorization: Bearer authenticates requests; browser cookies are ignored.\nCredentials are opaque, not JWTs. Expiration, revocation, independent action permissions\nand current resource access are checked against persistence on every request.\nSelected groups authorize their current members, in union with individually selected devices.\nNo action permission implies another. Resources outside the tenant or token's scope return 404.\nAll processed calls in an identified tenant are audited before data or mutations are released;\npersistence failures fail closed with 503. No credentials, commands or storage URLs are exposed.\n\nDefault shared limits per fixed one-minute window: 30 attempts per origin/tenant before\nauthentication (including valid requests), 120 requests per token, 600 per tenant.\nBackend configuration may change these limits. 429 includes Retry-After in seconds.\nRevocation blocks new calls; accepted work continues. Rotation immediately invalidates\nold credentials. Tenant lifecycle, billing and SSH trust restrictions remain authoritative.\n\nAdditive changes are allowed in v1; incompatible changes require documented deprecation\nand a new API version. The OpenAPI version does not change /api/v1.\n", "x-application-version": "2.1.0", "x-release-status": "released", "x-redoc-ce-version": "2.5.3" }, "servers": [ { "url": "https://{tenant_host}/api/v1", "variables": { "tenant_host": { "default": "tenant.example.com", "description": "Your tenant hostname; example.com is fictitious." } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Devices" }, { "name": "Runs" }, { "name": "Backups" } ], "paths": { "/device-groups": { "get": { "operationId": "get_device-groups", "summary": "List accessible device groups", "tags": [ "Devices" ], "x-required-scope": "devices:read", "description": "Requires **devices:read** independently of other permissions. Tenant and current device access are rechecked every request. Results sort by creation timestamp and ID, both descending. Signed opaque cursor, valid for 30 minutes. Bound to tenant, token,\npermission revision, filters and limit; changing these requires restarting pagination.\nFixed inclusion cutoff; current group membership, access and deletions are rechecked each\npage and may remove results. No global count or multi-request transactional snapshot.\nUse meta.next_cursor verbatim; null is the last page. Unknown or duplicate filters are rejected.", "parameters": [ { "name": "limit", "in": "query", "description": "Page size; filtering precedes pagination.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "description": "Signed opaque cursor, valid for 30 minutes. Bound to tenant, token,\npermission revision, filters and limit; changing these requires restarting pagination.\nFixed inclusion cutoff; current group membership, access and deletions are rechecked each\npage and may remove results. No global count or multi-request transactional snapshot.\nUse meta.next_cursor verbatim; null is the last page. Unknown or duplicate filters are rejected.", "schema": { "type": "string", "maxLength": 4096 } } ], "responses": { "400": { "description": "Malformed request or JSON. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "bad_request" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Malformed request or JSON." }, "correlation_id": "00000000000000000000000000000001" } } } }, "401": { "description": "Missing, invalid, expired, rotated or revoked credential. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "unauthorized" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer realm=\"public-api\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired, rotated or revoked credential." }, "correlation_id": "00000000000000000000000000000001" } } } }, "403": { "description": "Required permission is absent. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "forbidden" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Required permission is absent." }, "correlation_id": "00000000000000000000000000000001" } } } }, "404": { "description": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "not_found" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact." }, "correlation_id": "00000000000000000000000000000001" } } } }, "405": { "description": "HTTP method is not supported. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "method_not_allowed" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" }, "description": "Methods accepted by this resource, including automatic HEAD/OPTIONS where applicable.", "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "method_not_allowed", "message": "HTTP method is not supported." }, "correlation_id": "00000000000000000000000000000001" } } } }, "409": { "description": "Conflict: cursor_invalid. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "cursor_invalid" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "cursor_invalid", "message": "Conflict: cursor_invalid." }, "correlation_id": "00000000000000000000000000000001" } } } }, "410": { "description": "Tenant is inactive or environment is being closed. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "tenant_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "tenant_unavailable", "message": "Tenant is inactive or environment is being closed." }, "correlation_id": "00000000000000000000000000000001" } } } }, "422": { "description": "Unknown, duplicate or invalid query parameter. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "validation_failed" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Unknown, duplicate or invalid query parameter." }, "correlation_id": "00000000000000000000000000000001" } } } }, "429": { "description": "Shared request limit reached. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "rate_limited" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Shared request limit reached." }, "correlation_id": "00000000000000000000000000000001" } } } }, "500": { "description": "Unexpected HTTP error. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "internal_error" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected HTTP error." }, "correlation_id": "00000000000000000000000000000001" } } } }, "503": { "description": "Service, storage or audit persistence unavailable. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "Service, storage or audit persistence unavailable." }, "correlation_id": "00000000000000000000000000000001" } } } }, "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" }, "description": "Diagnostic ID, also in JSON meta." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GroupCollection" }, "meta": { "$ref": "#/components/schemas/CollectionMeta" } }, "required": [ "data", "meta" ], "additionalProperties": true }, "example": { "data": { "items": [ { "id": "group-example", "name": "Example group", "description": "Demo inventory", "created_at": "2026-01-01T12:00:00+00:00" } ] }, "meta": { "correlation_id": "00000000000000000000000000000001", "next_cursor": null, "snapshot_at": "2026-01-01T12:00:00+00:00" } } } } } } } }, "/devices": { "get": { "operationId": "get_devices", "summary": "List accessible devices", "tags": [ "Devices" ], "x-required-scope": "devices:read", "description": "Requires **devices:read** independently of other permissions. Tenant and current device access are rechecked every request. Results sort by creation timestamp and ID, both descending. Signed opaque cursor, valid for 30 minutes. Bound to tenant, token,\npermission revision, filters and limit; changing these requires restarting pagination.\nFixed inclusion cutoff; current group membership, access and deletions are rechecked each\npage and may remove results. No global count or multi-request transactional snapshot.\nUse meta.next_cursor verbatim; null is the last page. Unknown or duplicate filters are rejected.", "parameters": [ { "name": "limit", "in": "query", "description": "Page size; filtering precedes pagination.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "description": "Signed opaque cursor, valid for 30 minutes. Bound to tenant, token,\npermission revision, filters and limit; changing these requires restarting pagination.\nFixed inclusion cutoff; current group membership, access and deletions are rechecked each\npage and may remove results. No global count or multi-request transactional snapshot.\nUse meta.next_cursor verbatim; null is the last page. Unknown or duplicate filters are rejected.", "schema": { "type": "string", "maxLength": 4096 } }, { "name": "name", "in": "query", "description": "Case-insensitive substring of the device name.", "schema": { "type": "string", "maxLength": 200 }, "example": "Example" }, { "name": "group_id", "in": "query", "description": "Exact current group ID.", "schema": { "type": "string", "maxLength": 200 }, "example": "group-example" } ], "responses": { "400": { "description": "Malformed request or JSON. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "bad_request" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Malformed request or JSON." }, "correlation_id": "00000000000000000000000000000001" } } } }, "401": { "description": "Missing, invalid, expired, rotated or revoked credential. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "unauthorized" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer realm=\"public-api\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired, rotated or revoked credential." }, "correlation_id": "00000000000000000000000000000001" } } } }, "403": { "description": "Required permission is absent. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "forbidden" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Required permission is absent." }, "correlation_id": "00000000000000000000000000000001" } } } }, "404": { "description": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "not_found" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact." }, "correlation_id": "00000000000000000000000000000001" } } } }, "405": { "description": "HTTP method is not supported. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "method_not_allowed" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" }, "description": "Methods accepted by this resource, including automatic HEAD/OPTIONS where applicable.", "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "method_not_allowed", "message": "HTTP method is not supported." }, "correlation_id": "00000000000000000000000000000001" } } } }, "409": { "description": "Conflict: cursor_invalid. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "cursor_invalid" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "cursor_invalid", "message": "Conflict: cursor_invalid." }, "correlation_id": "00000000000000000000000000000001" } } } }, "410": { "description": "Tenant is inactive or environment is being closed. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "tenant_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "tenant_unavailable", "message": "Tenant is inactive or environment is being closed." }, "correlation_id": "00000000000000000000000000000001" } } } }, "422": { "description": "Unknown, duplicate or invalid query parameter. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "validation_failed" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Unknown, duplicate or invalid query parameter." }, "correlation_id": "00000000000000000000000000000001" } } } }, "429": { "description": "Shared request limit reached. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "rate_limited" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Shared request limit reached." }, "correlation_id": "00000000000000000000000000000001" } } } }, "500": { "description": "Unexpected HTTP error. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "internal_error" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected HTTP error." }, "correlation_id": "00000000000000000000000000000001" } } } }, "503": { "description": "Service, storage or audit persistence unavailable. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "Service, storage or audit persistence unavailable." }, "correlation_id": "00000000000000000000000000000001" } } } }, "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" }, "description": "Diagnostic ID, also in JSON meta." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeviceCollection" }, "meta": { "$ref": "#/components/schemas/CollectionMeta" } }, "required": [ "data", "meta" ], "additionalProperties": true }, "example": { "data": { "items": [ { "id": "device-example", "name": "Example router", "protocol": "ssh", "group_id": "group-example", "created_at": "2026-01-01T12:00:00+00:00", "last_status": "success", "last_backup_at": "2026-01-01T12:00:00+00:00" } ] }, "meta": { "correlation_id": "00000000000000000000000000000001", "next_cursor": null, "snapshot_at": "2026-01-01T12:00:00+00:00" } } } } } } } }, "/devices/{identifier}": { "get": { "operationId": "get_devices_by_id", "summary": "Read a device", "tags": [ "Devices" ], "x-required-scope": "devices:read", "description": "Requires **devices:read** independently of other permissions. Tenant and current device access are rechecked every request.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "description": "Opaque resource ID. Backup ID is the run ID of the eligible artifact.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "example": "device-example" } ], "responses": { "400": { "description": "Malformed request or JSON. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "bad_request" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Malformed request or JSON." }, "correlation_id": "00000000000000000000000000000001" } } } }, "401": { "description": "Missing, invalid, expired, rotated or revoked credential. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "unauthorized" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer realm=\"public-api\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired, rotated or revoked credential." }, "correlation_id": "00000000000000000000000000000001" } } } }, "403": { "description": "Required permission is absent. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "forbidden" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Required permission is absent." }, "correlation_id": "00000000000000000000000000000001" } } } }, "404": { "description": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "not_found" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact." }, "correlation_id": "00000000000000000000000000000001" } } } }, "405": { "description": "HTTP method is not supported. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "method_not_allowed" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" }, "description": "Methods accepted by this resource, including automatic HEAD/OPTIONS where applicable.", "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "method_not_allowed", "message": "HTTP method is not supported." }, "correlation_id": "00000000000000000000000000000001" } } } }, "410": { "description": "Tenant is inactive or environment is being closed. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "tenant_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "tenant_unavailable", "message": "Tenant is inactive or environment is being closed." }, "correlation_id": "00000000000000000000000000000001" } } } }, "429": { "description": "Shared request limit reached. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "rate_limited" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Shared request limit reached." }, "correlation_id": "00000000000000000000000000000001" } } } }, "500": { "description": "Unexpected HTTP error. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "internal_error" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected HTTP error." }, "correlation_id": "00000000000000000000000000000001" } } } }, "503": { "description": "Service, storage or audit persistence unavailable. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "Service, storage or audit persistence unavailable." }, "correlation_id": "00000000000000000000000000000001" } } } }, "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" }, "description": "Diagnostic ID, also in JSON meta." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Device" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": true }, "example": { "data": { "id": "device-example", "name": "Example router", "protocol": "ssh", "group_id": "group-example", "created_at": "2026-01-01T12:00:00+00:00", "last_status": "success", "last_backup_at": "2026-01-01T12:00:00+00:00" }, "meta": { "correlation_id": "00000000000000000000000000000001" } } } } } } } }, "/devices/{identifier}/runs": { "post": { "operationId": "post_devices_by_id_runs", "summary": "Run a backup", "tags": [ "Devices" ], "x-required-scope": "backups:run", "description": "Requires **backups:run** independently of other permissions. Tenant and current device access are rechecked every request. Asynchronous dispatch accepts only {}. An active run is reused; new external requests have a shared 60-second cooldown per tenant/device. Work is persisted before dispatch; scheduler recovery handles dispatch failure. Replay still requires valid current authorization and billing. Revocation does not cancel accepted work. Poll run_href using runs:read.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "description": "Opaque resource ID. Backup ID is the run ID of the eligible artifact.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "example": "device-example" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Printable ASCII key, 1–200 characters without whitespace. Stored for 24 hours, bound to tenant, token, route and normalized JSON body. Repeating an accepted key returns the original run; divergent body returns 409. A new invalid body returns 422.", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[!-~]+$" }, "example": "example-backup-request-001" } ], "responses": { "400": { "description": "Malformed request or JSON. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "bad_request" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Malformed request or JSON." }, "correlation_id": "00000000000000000000000000000001" } } } }, "401": { "description": "Missing, invalid, expired, rotated or revoked credential. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "unauthorized" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer realm=\"public-api\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired, rotated or revoked credential." }, "correlation_id": "00000000000000000000000000000001" } } } }, "403": { "description": "Required permission is absent, or billing disallows backup. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "forbidden" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Required permission is absent, or billing disallows backup." }, "correlation_id": "00000000000000000000000000000001" } } } }, "404": { "description": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "not_found" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact." }, "correlation_id": "00000000000000000000000000000001" } } } }, "405": { "description": "HTTP method is not supported. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "method_not_allowed" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" }, "description": "Methods accepted by this resource, including automatic HEAD/OPTIONS where applicable.", "example": "POST, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "method_not_allowed", "message": "HTTP method is not supported." }, "correlation_id": "00000000000000000000000000000001" } } } }, "409": { "description": "Conflict: tenant_read_only, host_key_required, idempotency_conflict, conflict. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "tenant_read_only", "host_key_required", "idempotency_conflict", "conflict" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "tenant_read_only", "message": "Conflict: tenant_read_only, host_key_required, idempotency_conflict, conflict." }, "correlation_id": "00000000000000000000000000000001" } } } }, "410": { "description": "Tenant is inactive or environment is being closed. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "tenant_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "tenant_unavailable", "message": "Tenant is inactive or environment is being closed." }, "correlation_id": "00000000000000000000000000000001" } } } }, "413": { "description": "Request exceeds 16 KiB, or download exceeds configured backup size limit. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "payload_too_large" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "Request exceeds 16 KiB, or download exceeds configured backup size limit." }, "correlation_id": "00000000000000000000000000000001" } } } }, "415": { "description": "Backup dispatch requires application/json. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "unsupported_media_type" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Backup dispatch requires application/json." }, "correlation_id": "00000000000000000000000000000001" } } } }, "422": { "description": "Unknown/duplicate/invalid filter, invalid body, or missing/invalid idempotency key. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "validation_failed", "idempotency_required" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Unknown/duplicate/invalid filter, invalid body, or missing/invalid idempotency key." }, "correlation_id": "00000000000000000000000000000001" } } } }, "429": { "description": "Shared request limit or 60-second device cooldown reached. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "rate_limited", "cooldown" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Shared request limit or 60-second device cooldown reached." }, "correlation_id": "00000000000000000000000000000001" } } } }, "500": { "description": "Unexpected HTTP error. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "internal_error" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected HTTP error." }, "correlation_id": "00000000000000000000000000000001" } } } }, "503": { "description": "Service, storage or audit persistence unavailable. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "Service, storage or audit persistence unavailable." }, "correlation_id": "00000000000000000000000000000001" } } } }, "202": { "description": "Accepted for asynchronous processing", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" }, "description": "Diagnostic ID, also in JSON meta." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AcceptedRun" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": true }, "example": { "data": { "run_id": "run-example", "run_href": "/api/v1/runs/run-example" }, "meta": { "correlation_id": "00000000000000000000000000000001" } } } } } }, "requestBody": { "required": true, "description": "Empty JSON object; request size is limited to 16 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } } } }, "/runs": { "get": { "operationId": "get_runs", "summary": "List backup runs", "tags": [ "Runs" ], "x-required-scope": "runs:read", "description": "Requires **runs:read** independently of other permissions. Tenant and current device access are rechecked every request. Results sort by run request timestamp and ID, both descending. Signed opaque cursor, valid for 30 minutes. Bound to tenant, token,\npermission revision, filters and limit; changing these requires restarting pagination.\nFixed inclusion cutoff; current group membership, access and deletions are rechecked each\npage and may remove results. No global count or multi-request transactional snapshot.\nUse meta.next_cursor verbatim; null is the last page. Unknown or duplicate filters are rejected.", "parameters": [ { "name": "limit", "in": "query", "description": "Page size; filtering precedes pagination.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "description": "Signed opaque cursor, valid for 30 minutes. Bound to tenant, token,\npermission revision, filters and limit; changing these requires restarting pagination.\nFixed inclusion cutoff; current group membership, access and deletions are rechecked each\npage and may remove results. No global count or multi-request transactional snapshot.\nUse meta.next_cursor verbatim; null is the last page. Unknown or duplicate filters are rejected.", "schema": { "type": "string", "maxLength": 4096 } }, { "name": "device_id", "in": "query", "description": "Exact device ID within authorized scope.", "schema": { "type": "string", "maxLength": 200 }, "example": "device-example" }, { "name": "status", "in": "query", "description": "Technical run state.", "schema": { "type": "string", "maxLength": 200, "enum": [ "queued", "running", "cancelling", "cancelled", "success", "failed" ] }, "example": "success" }, { "name": "from", "in": "query", "description": "Inclusive requested_at lower bound (also for backups). UTC date-time ending in uppercase Z (for example 2026-01-01T12:00:00Z); numeric offsets are rejected.", "schema": { "type": "string", "maxLength": 200, "format": "date-time", "pattern": "Z$" }, "example": "2026-01-01T12:00:00Z" }, { "name": "to", "in": "query", "description": "Inclusive requested_at upper bound in UTC ending in Z; must not precede from.", "schema": { "type": "string", "maxLength": 200, "format": "date-time", "pattern": "Z$" }, "example": "2026-01-01T12:00:00Z" } ], "responses": { "400": { "description": "Malformed request or JSON. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "bad_request" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Malformed request or JSON." }, "correlation_id": "00000000000000000000000000000001" } } } }, "401": { "description": "Missing, invalid, expired, rotated or revoked credential. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "unauthorized" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer realm=\"public-api\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired, rotated or revoked credential." }, "correlation_id": "00000000000000000000000000000001" } } } }, "403": { "description": "Required permission is absent. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "forbidden" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Required permission is absent." }, "correlation_id": "00000000000000000000000000000001" } } } }, "404": { "description": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "not_found" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact." }, "correlation_id": "00000000000000000000000000000001" } } } }, "405": { "description": "HTTP method is not supported. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "method_not_allowed" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" }, "description": "Methods accepted by this resource, including automatic HEAD/OPTIONS where applicable.", "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "method_not_allowed", "message": "HTTP method is not supported." }, "correlation_id": "00000000000000000000000000000001" } } } }, "409": { "description": "Conflict: cursor_invalid. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "cursor_invalid" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "cursor_invalid", "message": "Conflict: cursor_invalid." }, "correlation_id": "00000000000000000000000000000001" } } } }, "410": { "description": "Tenant is inactive or environment is being closed. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "tenant_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "tenant_unavailable", "message": "Tenant is inactive or environment is being closed." }, "correlation_id": "00000000000000000000000000000001" } } } }, "422": { "description": "Unknown, duplicate or invalid query parameter. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "validation_failed" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Unknown, duplicate or invalid query parameter." }, "correlation_id": "00000000000000000000000000000001" } } } }, "429": { "description": "Shared request limit reached. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "rate_limited" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Shared request limit reached." }, "correlation_id": "00000000000000000000000000000001" } } } }, "500": { "description": "Unexpected HTTP error. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "internal_error" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected HTTP error." }, "correlation_id": "00000000000000000000000000000001" } } } }, "503": { "description": "Service, storage or audit persistence unavailable. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "Service, storage or audit persistence unavailable." }, "correlation_id": "00000000000000000000000000000001" } } } }, "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" }, "description": "Diagnostic ID, also in JSON meta." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RunCollection" }, "meta": { "$ref": "#/components/schemas/CollectionMeta" } }, "required": [ "data", "meta" ], "additionalProperties": true }, "example": { "data": { "items": [ { "id": "run-example", "device_id": "device-example", "status": "success", "source": "external", "requested_at": "2026-01-01T12:00:00+00:00", "started_at": "2026-01-01T12:00:00+00:00", "finished_at": "2026-01-01T12:00:00+00:00", "transport_status": "completed", "validation_status": "valid", "reason_code": "", "pipeline_version": 1, "backup_id": "run-example" } ] }, "meta": { "correlation_id": "00000000000000000000000000000001", "next_cursor": null, "snapshot_at": "2026-01-01T12:00:00+00:00" } } } } } } } }, "/runs/{identifier}": { "get": { "operationId": "get_runs_by_id", "summary": "Read a backup run", "tags": [ "Runs" ], "x-required-scope": "runs:read", "description": "Requires **runs:read** independently of other permissions. Tenant and current device access are rechecked every request.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "description": "Opaque resource ID. Backup ID is the run ID of the eligible artifact.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "example": "run-example" } ], "responses": { "400": { "description": "Malformed request or JSON. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "bad_request" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Malformed request or JSON." }, "correlation_id": "00000000000000000000000000000001" } } } }, "401": { "description": "Missing, invalid, expired, rotated or revoked credential. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "unauthorized" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer realm=\"public-api\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired, rotated or revoked credential." }, "correlation_id": "00000000000000000000000000000001" } } } }, "403": { "description": "Required permission is absent. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "forbidden" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Required permission is absent." }, "correlation_id": "00000000000000000000000000000001" } } } }, "404": { "description": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "not_found" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact." }, "correlation_id": "00000000000000000000000000000001" } } } }, "405": { "description": "HTTP method is not supported. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "method_not_allowed" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" }, "description": "Methods accepted by this resource, including automatic HEAD/OPTIONS where applicable.", "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "method_not_allowed", "message": "HTTP method is not supported." }, "correlation_id": "00000000000000000000000000000001" } } } }, "410": { "description": "Tenant is inactive or environment is being closed. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "tenant_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "tenant_unavailable", "message": "Tenant is inactive or environment is being closed." }, "correlation_id": "00000000000000000000000000000001" } } } }, "429": { "description": "Shared request limit reached. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "rate_limited" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Shared request limit reached." }, "correlation_id": "00000000000000000000000000000001" } } } }, "500": { "description": "Unexpected HTTP error. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "internal_error" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected HTTP error." }, "correlation_id": "00000000000000000000000000000001" } } } }, "503": { "description": "Service, storage or audit persistence unavailable. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "Service, storage or audit persistence unavailable." }, "correlation_id": "00000000000000000000000000000001" } } } }, "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" }, "description": "Diagnostic ID, also in JSON meta." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Run" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": true }, "example": { "data": { "id": "run-example", "device_id": "device-example", "status": "success", "source": "external", "requested_at": "2026-01-01T12:00:00+00:00", "started_at": "2026-01-01T12:00:00+00:00", "finished_at": "2026-01-01T12:00:00+00:00", "transport_status": "completed", "validation_status": "valid", "reason_code": "", "pipeline_version": 1, "backup_id": "run-example" }, "meta": { "correlation_id": "00000000000000000000000000000001" } } } } } } } }, "/backups": { "get": { "operationId": "get_backups", "summary": "List eligible backup artifacts", "tags": [ "Backups" ], "x-required-scope": "backups:metadata:read", "description": "Requires **backups:metadata:read** independently of other permissions. Tenant and current device access are rechecked every request. Results sort by run request timestamp and ID, both descending. Signed opaque cursor, valid for 30 minutes. Bound to tenant, token,\npermission revision, filters and limit; changing these requires restarting pagination.\nFixed inclusion cutoff; current group membership, access and deletions are rechecked each\npage and may remove results. No global count or multi-request transactional snapshot.\nUse meta.next_cursor verbatim; null is the last page. Unknown or duplicate filters are rejected. Only success runs with an artifact and valid or legacy_unverified validation are eligible. Legacy validation is not a consolidated protection assessment.", "parameters": [ { "name": "limit", "in": "query", "description": "Page size; filtering precedes pagination.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "example": 50 }, { "name": "cursor", "in": "query", "description": "Signed opaque cursor, valid for 30 minutes. Bound to tenant, token,\npermission revision, filters and limit; changing these requires restarting pagination.\nFixed inclusion cutoff; current group membership, access and deletions are rechecked each\npage and may remove results. No global count or multi-request transactional snapshot.\nUse meta.next_cursor verbatim; null is the last page. Unknown or duplicate filters are rejected.", "schema": { "type": "string", "maxLength": 4096 } }, { "name": "device_id", "in": "query", "description": "Exact device ID within authorized scope.", "schema": { "type": "string", "maxLength": 200 }, "example": "device-example" }, { "name": "from", "in": "query", "description": "Inclusive requested_at lower bound (also for backups). UTC date-time ending in uppercase Z (for example 2026-01-01T12:00:00Z); numeric offsets are rejected.", "schema": { "type": "string", "maxLength": 200, "format": "date-time", "pattern": "Z$" }, "example": "2026-01-01T12:00:00Z" }, { "name": "to", "in": "query", "description": "Inclusive requested_at upper bound in UTC ending in Z; must not precede from.", "schema": { "type": "string", "maxLength": 200, "format": "date-time", "pattern": "Z$" }, "example": "2026-01-01T12:00:00Z" } ], "responses": { "400": { "description": "Malformed request or JSON. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "bad_request" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Malformed request or JSON." }, "correlation_id": "00000000000000000000000000000001" } } } }, "401": { "description": "Missing, invalid, expired, rotated or revoked credential. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "unauthorized" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer realm=\"public-api\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired, rotated or revoked credential." }, "correlation_id": "00000000000000000000000000000001" } } } }, "403": { "description": "Required permission is absent. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "forbidden" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Required permission is absent." }, "correlation_id": "00000000000000000000000000000001" } } } }, "404": { "description": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "not_found" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact." }, "correlation_id": "00000000000000000000000000000001" } } } }, "405": { "description": "HTTP method is not supported. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "method_not_allowed" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" }, "description": "Methods accepted by this resource, including automatic HEAD/OPTIONS where applicable.", "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "method_not_allowed", "message": "HTTP method is not supported." }, "correlation_id": "00000000000000000000000000000001" } } } }, "409": { "description": "Conflict: cursor_invalid. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "cursor_invalid" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "cursor_invalid", "message": "Conflict: cursor_invalid." }, "correlation_id": "00000000000000000000000000000001" } } } }, "410": { "description": "Tenant is inactive or environment is being closed. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "tenant_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "tenant_unavailable", "message": "Tenant is inactive or environment is being closed." }, "correlation_id": "00000000000000000000000000000001" } } } }, "422": { "description": "Unknown, duplicate or invalid query parameter. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "validation_failed" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Unknown, duplicate or invalid query parameter." }, "correlation_id": "00000000000000000000000000000001" } } } }, "429": { "description": "Shared request limit reached. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "rate_limited" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Shared request limit reached." }, "correlation_id": "00000000000000000000000000000001" } } } }, "500": { "description": "Unexpected HTTP error. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "internal_error" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected HTTP error." }, "correlation_id": "00000000000000000000000000000001" } } } }, "503": { "description": "Service, storage or audit persistence unavailable. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "Service, storage or audit persistence unavailable." }, "correlation_id": "00000000000000000000000000000001" } } } }, "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" }, "description": "Diagnostic ID, also in JSON meta." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BackupCollection" }, "meta": { "$ref": "#/components/schemas/CollectionMeta" } }, "required": [ "data", "meta" ], "additionalProperties": true }, "example": { "data": { "items": [ { "id": "run-example", "run_id": "run-example", "device_id": "device-example", "created_at": "2026-01-01T12:00:00+00:00", "size_bytes": 1234, "validation_status": "valid", "download_eligible": true } ] }, "meta": { "correlation_id": "00000000000000000000000000000001", "next_cursor": null, "snapshot_at": "2026-01-01T12:00:00+00:00" } } } } } } } }, "/backups/{identifier}": { "get": { "operationId": "get_backups_by_id", "summary": "Read backup metadata", "tags": [ "Backups" ], "x-required-scope": "backups:metadata:read", "description": "Requires **backups:metadata:read** independently of other permissions. Tenant and current device access are rechecked every request. Only success runs with an artifact and valid or legacy_unverified validation are eligible. Legacy validation is not a consolidated protection assessment.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "description": "Opaque resource ID. Backup ID is the run ID of the eligible artifact.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "example": "run-example" } ], "responses": { "400": { "description": "Malformed request or JSON. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "bad_request" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Malformed request or JSON." }, "correlation_id": "00000000000000000000000000000001" } } } }, "401": { "description": "Missing, invalid, expired, rotated or revoked credential. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "unauthorized" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer realm=\"public-api\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired, rotated or revoked credential." }, "correlation_id": "00000000000000000000000000000001" } } } }, "403": { "description": "Required permission is absent. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "forbidden" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Required permission is absent." }, "correlation_id": "00000000000000000000000000000001" } } } }, "404": { "description": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "not_found" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact." }, "correlation_id": "00000000000000000000000000000001" } } } }, "405": { "description": "HTTP method is not supported. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "method_not_allowed" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" }, "description": "Methods accepted by this resource, including automatic HEAD/OPTIONS where applicable.", "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "method_not_allowed", "message": "HTTP method is not supported." }, "correlation_id": "00000000000000000000000000000001" } } } }, "410": { "description": "Tenant is inactive or environment is being closed. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "tenant_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "tenant_unavailable", "message": "Tenant is inactive or environment is being closed." }, "correlation_id": "00000000000000000000000000000001" } } } }, "429": { "description": "Shared request limit reached. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "rate_limited" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Shared request limit reached." }, "correlation_id": "00000000000000000000000000000001" } } } }, "500": { "description": "Unexpected HTTP error. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "internal_error" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected HTTP error." }, "correlation_id": "00000000000000000000000000000001" } } } }, "503": { "description": "Service, storage or audit persistence unavailable. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "Service, storage or audit persistence unavailable." }, "correlation_id": "00000000000000000000000000000001" } } } }, "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" }, "description": "Diagnostic ID, also in JSON meta." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Backup" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": true }, "example": { "data": { "id": "run-example", "run_id": "run-example", "device_id": "device-example", "created_at": "2026-01-01T12:00:00+00:00", "size_bytes": 1234, "validation_status": "valid", "download_eligible": true }, "meta": { "correlation_id": "00000000000000000000000000000001" } } } } } } } }, "/backups/{identifier}/download": { "get": { "operationId": "get_backups_by_id_download", "summary": "Download a backup file", "tags": [ "Backups" ], "x-required-scope": "backups:download", "description": "Requires **backups:download** independently of other permissions. Tenant and current device access are rechecked every request. Only success runs with an artifact and valid or legacy_unverified validation are eligible. Legacy validation is not a consolidated protection assessment. HEAD preserves authorization and returns attachment headers without retrieving the file; body-dependent Content-Length is omitted and no transfer is started. Storage existence is confirmed by GET. Returns the file without external redirect or storage URL. Size/timeout and purge protections apply. Temporary files are private and cleaned after transfer. Failure after response starts closes the connection; no JSON is inserted into the file. Server completion does not prove client receipt.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "description": "Opaque resource ID. Backup ID is the run ID of the eligible artifact.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "example": "run-example" } ], "responses": { "400": { "description": "Malformed request or JSON. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "bad_request" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "Malformed request or JSON." }, "correlation_id": "00000000000000000000000000000001" } } } }, "401": { "description": "Missing, invalid, expired, rotated or revoked credential. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "unauthorized" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer realm=\"public-api\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired, rotated or revoked credential." }, "correlation_id": "00000000000000000000000000000001" } } } }, "403": { "description": "Required permission is absent. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "forbidden" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Required permission is absent." }, "correlation_id": "00000000000000000000000000000001" } } } }, "404": { "description": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "not_found" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Missing resource, unknown tenant, resource outside authorized scope, or missing storage artifact." }, "correlation_id": "00000000000000000000000000000001" } } } }, "405": { "description": "HTTP method is not supported. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "method_not_allowed" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Allow": { "schema": { "type": "string" }, "description": "Methods accepted by this resource, including automatic HEAD/OPTIONS where applicable.", "example": "GET, HEAD, OPTIONS" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "method_not_allowed", "message": "HTTP method is not supported." }, "correlation_id": "00000000000000000000000000000001" } } } }, "409": { "description": "Conflict: conflict. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "conflict" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Conflict: conflict." }, "correlation_id": "00000000000000000000000000000001" } } } }, "410": { "description": "Tenant is inactive or environment is being closed. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "tenant_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "tenant_unavailable", "message": "Tenant is inactive or environment is being closed." }, "correlation_id": "00000000000000000000000000000001" } } } }, "413": { "description": "Request exceeds 16 KiB, or download exceeds configured backup size limit. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "payload_too_large" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "Request exceeds 16 KiB, or download exceeds configured backup size limit." }, "correlation_id": "00000000000000000000000000000001" } } } }, "429": { "description": "Shared request limit reached. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "rate_limited" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds before retrying.", "example": 30 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Shared request limit reached." }, "correlation_id": "00000000000000000000000000000001" } } } }, "500": { "description": "Unexpected HTTP error. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "internal_error" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Unexpected HTTP error." }, "correlation_id": "00000000000000000000000000000001" } } } }, "503": { "description": "Service, storage or audit persistence unavailable. Errors before file transfer starts are safe JSON.", "x-error-codes": [ "service_unavailable" ], "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "Service, storage or audit persistence unavailable." }, "correlation_id": "00000000000000000000000000000001" } } } }, "200": { "description": "Success", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }, "X-Correlation-ID": { "schema": { "type": "string" }, "description": "Diagnostic ID, also in JSON meta." }, "Content-Disposition": { "schema": { "type": "string" }, "description": "attachment; original user-facing filename is preserved.", "example": "attachment; filename=\"example-backup.txt\"" }, "Content-Length": { "schema": { "type": "integer", "minimum": 0 }, "description": "File length when provided by the server." } }, "content": { "text/plain": { "schema": { "type": "string", "description": "Decompressed backup bytes delivered as an attachment; not a JSON envelope." } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Opaque", "description": "Send the tenant credential in Authorization: Bearer. Independent permissions: devices:read, runs:read, backups:metadata:read, backups:run, backups:download. Required permission is documented per operation; this is not OAuth." } }, "schemas": { "Group": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "description", "created_at" ], "additionalProperties": true, "examples": [ { "id": "group-example", "name": "Example group", "description": "Demo inventory", "created_at": "2026-01-01T12:00:00+00:00" } ] }, "Device": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "name": { "type": [ "string", "null" ] }, "protocol": { "type": [ "string", "null" ] }, "group_id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_status": { "type": [ "string", "null" ] }, "last_backup_at": { "type": [ "string", "null" ], "description": "Legacy last-backup timestamp text; may be empty or null." } }, "required": [ "id", "name", "protocol", "group_id", "created_at", "last_status", "last_backup_at" ], "additionalProperties": true, "examples": [ { "id": "device-example", "name": "Example router", "protocol": "ssh", "group_id": "group-example", "created_at": "2026-01-01T12:00:00+00:00", "last_status": "success", "last_backup_at": "2026-01-01T12:00:00+00:00" } ] }, "Run": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "device_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "status": { "type": "string", "x-extensible-enum": [ "queued", "running", "cancelling", "cancelled", "success", "failed" ], "description": "Known current values: queued, running, cancelling, cancelled, success, failed. Clients must tolerate future unknown states." }, "source": { "type": "string", "x-extensible-enum": [ "manual", "scheduled", "external", "reconciled" ], "description": "Known current values: manual, scheduled, external, reconciled. Clients must tolerate future unknown states." }, "requested_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "transport_status": { "type": "string", "x-extensible-enum": [ "unknown", "not_started", "completed", "timed_out", "disconnected", "failed", "cancelled" ], "description": "Known current values: unknown, not_started, completed, timed_out, disconnected, failed, cancelled. Clients must tolerate future unknown states." }, "validation_status": { "type": "string", "x-extensible-enum": [ "not_evaluated", "valid", "incomplete", "rejected", "legacy_unverified" ], "description": "Known current values: not_evaluated, valid, incomplete, rejected, legacy_unverified. Clients must tolerate future unknown states." }, "reason_code": { "type": "string", "description": "Technical reason code; empty when no reason applies." }, "pipeline_version": { "type": [ "integer", "null" ] }, "backup_id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128, "description": "Run ID of an eligible artifact, otherwise null. Metadata and download require their own permissions." } }, "required": [ "id", "device_id", "status", "source", "requested_at", "started_at", "finished_at", "transport_status", "validation_status", "reason_code", "pipeline_version", "backup_id" ], "additionalProperties": true, "examples": [ { "id": "run-example", "device_id": "device-example", "status": "success", "source": "external", "requested_at": "2026-01-01T12:00:00+00:00", "started_at": "2026-01-01T12:00:00+00:00", "finished_at": "2026-01-01T12:00:00+00:00", "transport_status": "completed", "validation_status": "valid", "reason_code": "", "pipeline_version": 1, "backup_id": "run-example" } ] }, "Backup": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "run_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "device_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "size_bytes": { "type": "integer", "minimum": 0, "description": "Uncompressed size recorded in metadata; zero when unavailable." }, "validation_status": { "type": "string", "x-extensible-enum": [ "valid", "legacy_unverified" ], "description": "Known current values: valid, legacy_unverified. Clients must tolerate future unknown states." }, "download_eligible": { "type": "boolean" } }, "required": [ "id", "run_id", "device_id", "created_at", "size_bytes", "validation_status", "download_eligible" ], "additionalProperties": true, "examples": [ { "id": "run-example", "run_id": "run-example", "device_id": "device-example", "created_at": "2026-01-01T12:00:00+00:00", "size_bytes": 1234, "validation_status": "valid", "download_eligible": true } ] }, "AcceptedRun": { "type": "object", "properties": { "run_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "maxLength": 128 }, "run_href": { "type": "string", "pattern": "^/api/v1/runs/", "description": "Relative public URL for polling; requires runs:read." } }, "required": [ "run_id", "run_href" ], "additionalProperties": true, "examples": [ { "run_id": "run-example", "run_href": "/api/v1/runs/run-example" } ] }, "Meta": { "type": "object", "properties": { "correlation_id": { "type": "string", "description": "Opaque diagnostic identifier; never a credential." } }, "required": [ "correlation_id" ], "additionalProperties": true, "examples": [ { "correlation_id": "00000000000000000000000000000001" } ] }, "CollectionMeta": { "type": "object", "properties": { "correlation_id": { "type": "string", "description": "Opaque diagnostic identifier; never a credential." }, "next_cursor": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Opaque signed cursor. Null marks the last page." }, "snapshot_at": { "type": "string", "format": "date-time", "description": "Inclusion cutoff, not a transactional snapshot." } }, "required": [ "correlation_id", "next_cursor", "snapshot_at" ], "additionalProperties": true, "examples": [ { "correlation_id": "00000000000000000000000000000001", "next_cursor": null, "snapshot_at": "2026-01-01T12:00:00+00:00" } ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable code; use this instead of the localized message." }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": true }, "correlation_id": { "type": "string", "description": "Opaque diagnostic identifier; never a credential." } }, "required": [ "error", "correlation_id" ], "additionalProperties": true, "examples": [ { "error": { "code": "not_found", "message": "Resource not found." }, "correlation_id": "00000000000000000000000000000001" } ] }, "GroupCollection": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Group" } } }, "required": [ "items" ], "additionalProperties": true }, "DeviceCollection": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Device" } } }, "required": [ "items" ], "additionalProperties": true }, "RunCollection": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Run" } } }, "required": [ "items" ], "additionalProperties": true }, "BackupCollection": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Backup" } } }, "required": [ "items" ], "additionalProperties": true } } } }